xshell 1.1.13 → 1.1.14

package/builder.d.ts

@@ -140,7 +140,9 @@ export declare class Bundler {
     build(print?: boolean): Promise<void>;
     close(): Promise<void>;
     build_all(print?: boolean): Promise<void>;
+    /** 打包构建 js, 构建 html, 复制依赖文件 */
     build_all_and_close(print?: boolean): Promise<void>;
+    /** 仅打包构建 js, 不复制依赖 */
     build_and_close(print?: boolean): Promise<void>;
     build_htmls(print?: {
         info: boolean;

package/builder.js

@@ -489,6 +489,7 @@ export class Bundler {
             this.target === 'web' && this.htmls && this.build_htmls({ info: print, files: false })
         ]);
     }
+    /** 打包构建 js, 构建 html, 复制依赖文件 */
     async build_all_and_close(print = true) {
         await Promise.all([
             this.build_and_close(print),
@@ -496,6 +497,7 @@ export class Bundler {
             this.target === 'web' && this.htmls && this.build_htmls({ info: print, files: false })
         ]);
     }
+    /** 仅打包构建 js, 不复制依赖 */
     async build_and_close(print = true) {
         await this.build(print);
         await this.close();

package/net.browser.d.ts

@@ -66,7 +66,7 @@ export declare function request(url: string | URL, options: RequestOptions): Pro
 /** 发起 http 请求并将响应体作为 json 解析 */
 export declare function request_json<T = any>(url: string, options?: RequestOptions): Promise<T>;
 export declare class WebSocketConnectionError extends Error {
-    name: string;
+    name: "WebSocketConnectionError";
     url: string;
     protocols?: string[];
     websocket: WebSocket;

package/net.d.ts

@@ -71,6 +71,13 @@ export interface RequestError extends Error {
     response?: FullResponse<string>;
     [inspect.custom]: Function;
 }
+export interface StatusCodeError {
+    status: number;
+}
+export declare class StatusCodeError extends Error {
+    name: "StatusCodeError";
+    constructor(status: number, url: string);
+}
 /**
     - url: 必须是完整 url
     - options?:
@@ -91,7 +98,7 @@ export interface RequestError extends Error {
         - encoding?: `根据网页 content-type: charset=gb18030 提取 || 'utf-8'`  传入 'binary' 时返回 Buffer
              (只对非 raw 的请求起作用)
         - retries?: `false` 可以传入 true (默认 2 次) 或 重试次数
-        - timeout?: `5 * 1000` 超时后会抛出 error.name 为 'TimeoutError' 的 error, 可以传入 0 来禁用超时
+        - timeout?: `5 * 1000` 超时后会抛出 error.name 为 'TimeoutError' 的 error (但类型不是 utils.ts 中的 TimeoutError), 可以传入 0 来禁用超时
         - auth?: BasicAuth | BearerAuth
         - cookies?: 需要额外添加到请求的 cookies, 默认情况下携带了 MemoryCookieStore 中保存的之前 http 响应中的 cookies
         - raw?: `false` 传入后返回整个 response (RawResponse)，body 为 Readable
@@ -112,20 +119,8 @@ 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>;
-/** post json to http://localhost:8421/api/rpc
-    - func: function name
-    - args?: argument array
-    - options?:
-        - ignore?: `false` wait for execution but do not serialize result to response
-        - async?: `false` do not wait for exec
-*/
-export declare function rpc(func: string, args?: any[], { url, async: _async, ignore }?: {
-    url?: string;
-    async?: boolean;
-    ignore?: boolean;
-}): Promise<any>;
 export declare class WebSocketConnectionError extends Error {
-    name: string;
+    name: "WebSocketConnectionError";
     url: string;
     protocols?: string[];
     event: CloseEvent | ErrorEvent;

package/net.js

@@ -3,7 +3,7 @@ import { buffer as stream_to_buffer, text as stream_to_text } from 'stream/consu
 import { isReadable } from 'stream';
 import { t } from "./i18n/instance.js";
 import "./prototype.js";
-import { inspect, concat, assert, genid, delay, Lock, encode, decode, pipe_with_error, map_values, unique, timeout, check } from "./utils.js";
+import { inspect, concat, assert, genid, delay, Lock, encode, decode, pipe_with_error, map_values, unique, timeout, check, colored } from "./utils.js";
 export const WebSocketConnecting = 0;
 export const WebSocketOpen = 1;
 export const WebSocketClosing = 2;
@@ -57,16 +57,27 @@ async function request_retry(url, options, _timeout, retries = 0, count = 0, pri
             if (count < retries) {
                 const duration = 2 ** count;
                 if (print.retry)
-                    console.log(`${t('等待 {{duration}} 秒后重试 request (已尝试 {{_count}} 次) …', { duration, _count: count + 1 }).yellow}  ${url.toString().blue.underline}`);
+                    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
-                throw Object.assign(new Error(`request 超时: ${url.toString()}`), { name: 'TimeoutError' });
+            else {
+                const seconds = _timeout / 1000;
+                throw Object.assign(new Error(`请求超过 ${seconds.toFixed(seconds < 1 ? 1 : 0)} 秒等待时间: ${url.toString()}`), { name: 'TimeoutError' });
+            }
         else
             throw error;
     }
 }
+export class StatusCodeError extends Error {
+    name = 'StatusCodeError';
+    constructor(status, url) {
+        super(`状态码 ${status}: ${url}`);
+        Object.defineProperties(this, {
+            status: { value: status }
+        });
+    }
+}
 export async function request(url, options = {}) {
     let { default: undici, ProxyAgent: UndiciProxyAgent, FormData } = await import('undici');
     UndiciProxyAgent ??= undici.ProxyAgent;
@@ -117,11 +128,11 @@ export async function request(url, options = {}) {
         headers.cookie = request_cookies.map(cookie => cookie.cookieString())
             .join('; ');
     if (_headers) {
-        assert(Object.getPrototypeOf(_headers)?.constructor.name !== 'Headers');
+        check(Object.getPrototypeOf(_headers)?.constructor.name !== 'Headers');
         for (const key in _headers)
             // 可能在 http/2 的 response 中会有这样开头的保留 headers, 在透传时忽略比较好
             if (!key.startsWith(':') && !key.startsWith('sec-') && !drop_request_headers.has(key)) {
-                assert(key === key.toLowerCase(), t('传入 request 的 headers 参数中 key 应该都是小写的，实际为 {{key}}', { key }));
+                check(key === key.toLowerCase(), `传入 request 的 headers 参数中 key 应该都是小写的，实际为 ${key}`);
                 headers[key] = _headers[key];
             }
     }
@@ -142,9 +153,7 @@ export async function request(url, options = {}) {
                 return dispatcher;
             })();
         })(),
-        // todo: 强制手动处理重定向，来正确处理 cookie ?
-        maxRedirections: redirect === 'follow' ? 5 : 0,
-        // 下面这些 timeout 都不是总的时间，没法用
+        // 下面这些 timeout 都不是总的时间
         headersTimeout: timeout,
         // 从收完 headers 开始算
         bodyTimeout: timeout,
@@ -214,7 +223,7 @@ export async function request(url, options = {}) {
                     body = pipe_with_error(_body, zlib.createBrotliDecompress());
                     break;
                 default:
-                    throw new Error(t('不支持 content-encoding: {{encoding}} 的 http 请求', { encoding: content_encoding.quote() }));
+                    throw new Error(`不支持 content-encoding: ${content_encoding.quote()} 的 http 请求`);
             }
         }
         response = {
@@ -223,85 +232,49 @@ export async function request(url, options = {}) {
             body
         };
         if (!((200 <= status && status <= 299) || status === 304 || (redirect === 'manual' && 300 <= status && status < 400)))
-            throw Object.assign(new Error(t('状态码 {{status}}, 非 2xx: {{url}}', { status: response.status, url })), { name: 'StatusCodeError' });
+            throw new StatusCodeError(status, url.toString());
     }
     catch (error) {
-        ;
-        error.url = url;
-        error.options = options;
-        if (response)
-            error.response = {
-                status: response.status,
-                headers: response.headers,
-                body: await stream_to_text(response.body),
-            };
-        error[inspect.custom] = (depth, options, inspect) => {
-            const { colors } = options;
-            let _method = method || 'GET';
-            if (colors)
-                _method = _method.red;
-            let _url = urlstr;
-            if (colors)
-                _url = _url.blue.underline;
-            let s = '\n' +
-                `${_method} ${_url}\n`;
-            if (queries && Object.keys(queries).length) {
-                let _query = t('请求参数:');
-                if (colors)
-                    _query = _query.yellow;
-                s += _query + '\n' +
-                    inspect(queries, options) + '\n';
-            }
-            if (body !== undefined) {
-                let _body = t('请求体:');
-                if (colors)
-                    _body = _body.yellow;
-                s += _body + '\n' +
-                    inspect(body, options) + '\n';
-            }
-            if (error.name === 'StatusCodeError') {
-                let _status = t('响应状态码:');
-                if (colors)
-                    _status = _status.yellow;
-                let _code = String(response.status);
-                if (colors)
-                    _code = _code.red;
-                s += _status + ' ' + _code + '\n';
-            }
-            else if (error.name === 'TimeoutError') {
-                let _timeout = t('超过等待时间:');
-                if (colors)
-                    _timeout = _timeout.red;
-                s += `${_timeout} ${timeout} ms\n`;
-            }
-            if (response) {
-                let _headers = t('响应头:');
-                if (colors)
-                    _headers = _headers.yellow;
-                s += _headers + '\n';
-                for (const key in response.headers) {
-                    const value = response.headers[key];
-                    s += `${key}: ${value}\n`;
+        response ??= error.response;
+        throw Object.defineProperties(error, {
+            url: { value: url },
+            options: { value: options },
+            ...response ? {
+                response: {
+                    value: {
+                        status: response.status,
+                        headers: response.headers,
+                        body: await stream_to_text(response.body),
+                    }
                 }
-                if (error.response.body) {
-                    let _body = t('响应体:');
-                    if (colors)
-                        _body = _body.yellow;
-                    s += _body + '\n' +
-                        error.response.body + '\n';
+            } : {},
+            [inspect.custom]: {
+                value(depth, options, inspect) {
+                    const { colors } = options;
+                    const c = (str, color) => colored(str, color, colors);
+                    let s = '\n' +
+                        `${c(method || 'GET', 'red')} ${c(c(urlstr, 'blue'), 'underline')}\n`;
+                    if (queries && Object.keys(queries).length)
+                        s += c('请求参数:\n', 'yellow') +
+                            inspect(queries, options).ensure_end();
+                    if (body !== undefined)
+                        s += c('请求体:\n', 'yellow') +
+                            inspect(body, options).ensure_end();
+                    if (response) {
+                        s += c('响应头:\n', 'yellow');
+                        for (const key in response.headers) {
+                            const value = response.headers[key];
+                            s += `${key}: ${value}\n`;
+                        }
+                        if (error.response.body)
+                            s += c('响应体:\n', 'yellow') +
+                                error.response.body.toString().ensure_end();
+                    }
+                    s += inspect(error, { ...options, customInspect: false });
+                    return s;
                 }
             }
-            let _stack = t('调用栈:');
-            if (colors)
-                _stack = _stack.yellow;
-            s += _stack + '\n';
-            if (error.cause)
-                s += inspect(error.cause, options) + '\n';
-            s += error.stack + '\n' +
-                '\n';
-            return s;
-        };
-        throw error;
+        });
     }
     if (raw)
         return response;
@@ -337,26 +310,6 @@ export async function request_json(url, options) {
         throw error;
     }
 }
-// ------------------------------------ rpc client
-/** post json to http://localhost:8421/api/rpc
-    - func: function name
-    - args?: argument array
-    - options?:
-        - ignore?: `false` wait for execution but do not serialize result to response
-        - async?: `false` do not wait for exec
-*/
-export async function rpc(func, args, { url = 'http://localhost:8421/api/rpc', async: _async = false, ignore = false } = {}) {
-    if (!func)
-        throw new Error('rpc argument error: no func');
-    return request_json(url, {
-        body: {
-            func,
-            args,
-            async: _async,
-            ignore,
-        }
-    });
-}
 export class WebSocketConnectionError extends Error {
     name = 'WebSocketConnectionError';
     // 这里不保留 websocket 引用，防止循环引用导致 JSON 序列化失败

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xshell",
-    "version": "1.1.13",
+    "version": "1.1.14",
     "type": "module",
     "main": "./index.js",
     "bin": {

package/path.d.ts

@@ -54,7 +54,7 @@ export declare function extname(path: string): string;
 /** `/` */
 export declare const sep = "/";
 /** The platform-specific file delimiter. ';' or ':'. */
-export declare const delimiter: ":" | ";";
+export declare const delimiter: ";" | ":";
 /** Returns an object from a path string - the opposite of format().
     @param path path to evaluate.
     @throws {TypeError} if `path` is not a string. */
@@ -81,7 +81,7 @@ export declare let path: {
     basename: typeof basename;
     extname: typeof extname;
     sep: string;
-    delimiter: ":" | ";";
+    delimiter: ";" | ":";
     parse: typeof parse;
     format: typeof format;
     toNamespacedPath: typeof toNamespacedPath;

package/process.d.ts

@@ -1,8 +1,8 @@
+import type { InspectOptions } from 'util';
 import { type ChildProcess } from 'child_process';
 import './prototype.ts';
 import type { Encoding } from './file.ts';
 import type { MyProxy } from './net.ts';
-import { inspect } from './utils.ts';
 export declare const sea: boolean;
 export declare const exe_nodejs: string;
 export declare const platform: NodeJS.Platform;
@@ -103,8 +103,7 @@ export interface CallResult<TOutput extends string | Buffer = string> {
     child: ChildProcess;
     print: FullPrintOptions;
 }
-export declare class CallError<TOutput extends string | Buffer = string> extends Error {
-    name: string;
+export interface CallError<TOutput extends string | Buffer = string> extends Error {
     pid: number;
     stdout: TOutput;
     stderr: TOutput;
@@ -113,8 +112,11 @@ export declare class CallError<TOutput extends string | Buffer = string> extends
     command: string;
     child: ChildProcess;
     print: FullPrintOptions;
+}
+export declare class CallError<TOutput extends string | Buffer = string> extends Error {
+    name: "CallError";
     constructor({ message, pid, stdout, stderr, code, signal, command, child, print }: CallResult<TOutput>);
-    [inspect.custom](): string;
+    [inspect.custom](depth: number, options: InspectOptions, inspect: Function): string;
 }
 /** 调用可执行文件，获取返回结果，错误时抛出 CallError
     - exe: .exe 路径或文件名 (建议使用路径，跳过 path 搜索，性能更高)

package/process.js

@@ -2,14 +2,14 @@ import { spawn } from 'child_process';
 import os from 'os';
 import node_sea from 'node:sea';
 import "./prototype.js";
-import { inspect, DecoderStream, filter_values, check } from "./utils.js";
+import { inspect, DecoderStream, filter_values, check, colored } from "./utils.js";
 export const sea = node_sea.isSea();
 export const exe_nodejs = process.execPath.fp;
 export const platform = os.platform();
 export const username = os.userInfo().username;
 export const noprint = { print: false };
 export const print_no_command = { print: { command: false, code: false, stdout: true, stderr: true } };
-async function prepare_spawn(detached, exe, args, { cwd, window: _window = true, envs, 
+async function prepare_spawn(detached, exe, args, { cwd, window: _window, envs, 
 // @ts-ignore
 input, fp_stdin, fp_stdout, fp_stderr, print = true, proxy, 
 // @ts-ignore
@@ -94,7 +94,7 @@ stdio }) {
             cwd,
             shell: false,
             // processhacker 在 windowsHide 为 true 时不显示窗口
-            windowsHide: !_window,
+            windowsHide: _window ?? Boolean(!detached || fp_stdout),
             detached,
             stdio,
             ...envs_ ? { env: envs_ } : {}
@@ -128,29 +128,29 @@ export async function start(exe, args = [], options = {}) {
 }
 export class CallError extends Error {
     name = 'CallError';
-    pid;
-    stdout;
-    stderr;
-    code;
-    signal;
-    command;
-    child;
-    print;
     constructor({ message, pid, stdout, stderr, code, signal, command, child, print }) {
         super(message);
-        this.pid = pid;
-        this.stdout = stdout;
-        this.stderr = stderr;
-        this.code = code;
-        this.signal = signal;
-        this.command = command;
-        this.child = child;
-        this.print = print;
+        // defineProperty 默认 enumerable: false，不会在 inspect 中显示
+        Object.defineProperties(this, {
+            pid: { value: pid },
+            stdout: { value: stdout },
+            stderr: { value: stderr },
+            code: { value: code },
+            signal: { value: signal },
+            command: { value: command },
+            child: { value: child },
+            print: { value: print }
+        });
     }
-    [inspect.custom]() {
-        return (!this.print.stdout && this.stdout ? `标准输出:\n${this.stdout}\n` : '') +
-            (!this.print.stderr && this.stderr ? `标准错误:\n${this.stderr}\n` : '') +
-            this.stack;
+    [inspect.custom](depth, options, inspect) {
+        const { colors } = options;
+        return (!this.print.stdout && this.stdout
+            ? `${colored('标准输出:\n', 'yellow', colors)}${this.stdout.toString().ensure_end()}`
+            : '') +
+            (!this.print.stderr && this.stderr
+                ? `${colored('标准错误:\n', 'yellow', colors)}${this.stderr.toString().ensure_end()}`
+                : '') +
+            inspect(this, { ...options, customInspect: false });
     }
 }
 export async function call(exe, args = [], options = {}) {

package/prototype.browser.d.ts

@@ -92,6 +92,10 @@ declare global {
         strip_end(this: string, suffix: string, validate?: boolean): string;
         /** 返回去掉 suffix 结尾的字符串，如果没有以 suffix 结尾则返回原字符串 */
         strip_if_end(this: string, suffix: string): string;
+        /** 确保字符串以 prefix 开头，否则在头部追加 prefix */
+        ensure_start(this: string, prefix: string): string;
+        /** 确保字符串以 suffix (默认 '\n') 结尾，否则在尾部追加 suffix */
+        ensure_end(this: string, suffix?: string): string;
         /** 从 search 字符串出现的位置开始截取到最后
             - options?:
                 - include?: `false` 传 true 时包括 search 部分

package/prototype.browser.js

@@ -287,6 +287,12 @@ Object.defineProperties(String.prototype, {
         strip_if_end(suffix) {
             return this.endsWith(suffix) ? this.slice(0, -suffix.length) : this;
         },
+        ensure_start(prefix) {
+            return this.startsWith(prefix) ? this : prefix + this;
+        },
+        ensure_end(suffix = '\n') {
+            return this.endsWith(suffix) ? this : this + suffix;
+        },
         slice_from(search, { include = false, last = false } = {}) {
             const i = last ? this.lastIndexOf(search) : this.indexOf(search);
             if (i === -1)

package/prototype.d.ts

@@ -114,6 +114,10 @@ declare global {
         strip_end(this: string, suffix: string, validate?: boolean): string;
         /** 返回去掉 suffix 结尾的字符串，如果没有以 suffix 结尾则返回原字符串 */
         strip_if_end(this: string, suffix: string): string;
+        /** 确保字符串以 prefix 开头，否则在头部追加 prefix */
+        ensure_start(this: string, prefix: string): string;
+        /** 确保字符串以 suffix (默认 '\n') 结尾，否则在尾部追加 suffix */
+        ensure_end(this: string, suffix?: string): string;
         /** 从 search 字符串出现的位置开始截取到最后
             - options?:
                 - include?: `false` 传 true 时包括 search 部分

package/prototype.js

@@ -309,6 +309,12 @@ if (!globalThis.my_prototype_defined) {
             strip_if_end(suffix) {
                 return this.endsWith(suffix) ? this.slice(0, -suffix.length) : this;
             },
+            ensure_start(prefix) {
+                return this.startsWith(prefix) ? this : prefix + this;
+            },
+            ensure_end(suffix = '\n') {
+                return this.endsWith(suffix) ? this : this + suffix;
+            },
             slice_from(search, { include = false, last = false } = {}) {
                 const i = last ? this.lastIndexOf(search) : this.indexOf(search);
                 if (i === -1)
@@ -344,6 +350,9 @@ if (!globalThis.my_prototype_defined) {
                     .replace(new RegExp(cjk + '([~!;:,\\.\\?\u2026])([A-Za-z0-9])', 'g'), '$1$2 $3')
                     .replace(new RegExp(cjk + '([A-Za-z0-9`\\$%\\^&\\*\\-=\\+\\\\\\|\\/@\u00a1-\u00ff\u2022\u2027\u2150-\u218f])', 'g'), '$1 $2')
                     .replace(new RegExp('([A-Za-z0-9`\\$%\\^&\\*\\-=\\+\\\\\\|\\/@\u00a1-\u00ff\u2022\u2027\u2150-\u218f])' + cjk, 'g'), '$1 $2');
+            },
+            to_backslash() {
+                return this.replaceAll('/', '\\');
             }
         }),
         // ------------ colors
@@ -404,11 +413,6 @@ if (!globalThis.my_prototype_defined) {
                     ? ''
                     : fname.slice(index + 1);
             }
-        }),
-        ...to_method_property_descriptors({
-            to_backslash() {
-                return this.replaceAll('/', '\\');
-            }
         })
     });
     // ------------------------------------ Date.prototype

package/utils.browser.d.ts

@@ -22,7 +22,7 @@ export declare function delay(milliseconds: number, { signal }?: {
     signal?: AbortSignal;
 }): Promise<void>;
 export declare class TimeoutError extends Error {
-    constructor(message?: string, options?: ErrorOptions);
+    name: "TimeoutError";
 }
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后
     - 如果传入了 on_timeout 参数: 调用 on_timeout，返回 null
@@ -79,11 +79,13 @@ export declare function encode(str: string): Uint8Array<ArrayBufferLike>;
     在流式处理 (buffer 可能不完整) 时，应使用独立的 TextDecoder 实例调用 decode(buffer, { stream: true }) */
 export declare function decode(buffer: Uint8Array): string;
 /** 字符串字典序比较 */
-export declare function strcmp(l: string, r: string): 0 | 1 | -1;
+export declare function strcmp(l: string, r: string): 1 | 0 | -1;
 /** 比较 1.10.02 这种版本号
     - l, r: 两个版本号字符串
     - loose?: 宽松模式，允许两个版本号格式（位数）不一致 */
 export declare function vercmp(l: string, r: string, loose?: boolean): number;
+/** 过滤符合 pattern 的行 */
+export declare function grep(str: string, pattern: string | RegExp): string;
 /** 模糊过滤字符串列表或对象列表，常用于根据用户输入补全或搜索过滤
     - query: 查询字符串，要求为全小写
     - list: 要过滤的列表

package/utils.browser.js

@@ -74,10 +74,7 @@ export async function delay(milliseconds, { signal } = {}) {
     });
 }
 export class TimeoutError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = this.constructor.name;
-    }
+    name = 'TimeoutError';
 }
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后
     - 如果传入了 on_timeout 参数: 调用 on_timeout，返回 null
@@ -262,6 +259,14 @@ export function vercmp(l, r, loose = false) {
     // loose 下按短的优先，否则应该一样，为 0
     return lparts.length - rparts.length;
 }
+/** 过滤符合 pattern 的行 */
+export function grep(str, pattern) {
+    return str.split_lines()
+        .filter(typeof pattern === 'string'
+        ? line => line.includes(pattern)
+        : line => pattern.test(line))
+        .join_lines();
+}
 /** 模糊过滤字符串列表或对象列表，常用于根据用户输入补全或搜索过滤
     - query: 查询字符串，要求为全小写
     - list: 要过滤的列表

package/utils.d.ts

@@ -40,11 +40,13 @@ export declare function filter_values<TObj extends Record<string, any>>(obj: TOb
 /** 忽略对象中的 keys, 返回新对象 */
 export declare function omit<TObj>(obj: TObj, omit_keys: string[]): TObj;
 /** 字符串字典序比较 */
-export declare function strcmp(l: string, r: string): 0 | 1 | -1;
+export declare function strcmp(l: string, r: string): 1 | 0 | -1;
 /** 比较 1.10.02 这种版本号
     - l, r: 两个版本号字符串
     - loose?: 宽松模式，允许两个版本号格式（位数）不一致 */
 export declare function vercmp(l: string, r: string, loose?: boolean): number;
+/** 过滤符合 pattern 的行 */
+export declare function grep(str: string, pattern: string | RegExp): string;
 /** 模糊过滤字符串列表或对象列表，常用于根据用户输入补全或搜索过滤
     - query: 查询字符串，要求为全小写
     - list: 要过滤的列表
@@ -86,7 +88,7 @@ export declare class Timer {
 export declare function log_line(): void;
 export declare function delay(milliseconds: number, options?: TimerOptions): Promise<void>;
 export declare class TimeoutError extends Error {
-    constructor(message?: string, options?: ErrorOptions);
+    name: "TimeoutError";
 }
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后
     - 如果传入了 on_timeout 参数: 调用 on_timeout，返回 null
@@ -152,8 +154,11 @@ export declare function inspect(obj: any, options?: util.InspectOptions & {
     limit?: number;
     omit?: string[];
 }): string;
+/** 根据 enabled 选项返回有 / 无颜色的字符串 (str) */
+export declare function colored(str: string, color: string, enabled?: boolean): any;
 export declare namespace inspect {
     const custom: typeof util.inspect.custom;
+    const defaultOptions: util.InspectOptions;
 }
 /** npm map-stream
     filter will reemit the data if cb(err,pass) pass is truthy

package/utils.js

@@ -132,6 +132,14 @@ export function vercmp(l, r, loose = false) {
     // loose 下按短的优先，否则应该一样，为 0
     return lparts.length - rparts.length;
 }
+/** 过滤符合 pattern 的行 */
+export function grep(str, pattern) {
+    return str.split_lines()
+        .filter(typeof pattern === 'string'
+        ? line => line.includes(pattern)
+        : line => pattern.test(line))
+        .join_lines();
+}
 /** 模糊过滤字符串列表或对象列表，常用于根据用户输入补全或搜索过滤
     - query: 查询字符串，要求为全小写
     - list: 要过滤的列表
@@ -270,10 +278,7 @@ export async function delay(milliseconds, options) {
     return timers.setTimeout(milliseconds, undefined, options);
 }
 export class TimeoutError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = this.constructor.name;
-    }
+    name = 'TimeoutError';
 }
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后
     - 如果传入了 on_timeout 参数: 调用 on_timeout，返回 null
@@ -449,8 +454,13 @@ export function inspect(obj, options = {}) {
     else
         return text;
 }
+/** 根据 enabled 选项返回有 / 无颜色的字符串 (str) */
+export function colored(str, color, enabled = inspect.defaultOptions.colors) {
+    return enabled ? str[color] : str;
+}
 (function (inspect) {
     inspect.custom = util.inspect.custom;
+    inspect.defaultOptions = util.inspect.defaultOptions;
 })(inspect || (inspect = {}));
 // ------------------------------------ stream
 /** npm map-stream