xshell 1.1.25 → 1.2.0

package/net.d.ts

@@ -3,6 +3,7 @@ import type { FormData } from 'undici';
 import type { WebSocket, CloseEvent, ErrorEvent } from 'ws';
 import type { Cookie, CookieJar, MemoryCookieStore } from 'tough-cookie';
 import './prototype.ts';
+import { type Message } from './io.ts';
 import type { Encoding } from './file.ts';
 import { inspect, Lock } from './utils.ts';
 export type { WebSocket };
@@ -167,33 +168,6 @@ on_message, on_error, on_close, proxy, print, }: {
     - void: 什么都不做
     - 以上的 promise */
 export type MessageHandler<TData extends any[] = any[]> = (message: Message<TData>, websocket?: WebSocket) => void | any[] | Promise<void | any[]>;
-/** 二进制消息格式
-    - json.length (小端序): 4 字节
-    - json 数据
-    - binary 数据 */
-export interface Message<TData extends any[] = any[]> {
-    /** rpc id: 在 rpc 系统中认为是唯一的。用来在单个 websocket 连接上复用多个 rpc 请求。多个相同 id 的 message 组成一个请求流 */
-    id?: number;
-    /** 只在 rpc 发起时指定被调用的 function name，发起时 rpc 时必传 */
-    func?: string;
-    /** 通过这个 flag 主动表明这是发往对方的最后一个 message, 对方可以销毁 handler 了
-        并非强制，可以不说明，由双方的函数自己约定
-    */
-    done?: boolean;
-    /** 通知对方这里产生的错误，本质上类似 data 也是一种数据，并不代表 rpc 的结束，后续可能继续有 rpc message 交换 */
-    error?: Error;
-    /** data 是一个数组, 作为:
-        - rpc 发起方调用 func 的参数，或者请求流 message 携带的数据
-        - 结果或者响应流的数据，传给请求发起方
-        
-        里面是可序列化为 json 的 js 变量，或者是 Uint8Array
-        Uint8Array 的参数处理后被替换为 Uint8Array.byteLength, 并将下标记录在 bins 中
-        
-        注意: 数组中如果有 undefined 值，传输到对面会变成 null 值 */
-    data?: TData;
-    /** bins: data 中哪些下标对应的原始值是 Uint8Array 类型的，如: [0, 3] */
-    bins?: number[];
-}
 /** 自动保持 remote 连接，只对 initiator 且传入 url 有效，
     - 在未连接，或 websocket on_error 检测到连接断开后以 reconnect_interval 间隔尝试 remote.call(func) 重连
     - 在连接状态下以 heartbeat_interval 间隔发送心跳包确保连接状态
@@ -257,9 +231,6 @@ export declare class Remote {
     keeping: boolean;
     reconnecting: boolean;
     disconnected: boolean;
-    /** 使用 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<ArrayBuffer>;
     /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
         作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
     constructor({ url, funcs, print, verbose, websocket, keeper, on_error, }?: {

package/net.js

@@ -3,7 +3,8 @@ 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, colored } from "./utils.js";
+import { message_symbol, pack, parse } from "./io.js";
+import { inspect, assert, genid, delay, Lock, pipe_with_error, map_values, unique, timeout, check, colored } from "./utils.js";
 export const WebSocketConnecting = 0;
 export const WebSocketOpen = 1;
 export const WebSocketClosing = 2;
@@ -474,54 +475,6 @@ export class Remote {
     keeping = false;
     reconnecting = false;
     disconnected = false;
-    /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
-    static parse(buffer) {
-        const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-        const len_json = dv.getUint32(0, true);
-        let offset = 4 + len_json;
-        let message = JSON.parse(decode(buffer.subarray(4, offset)));
-        message.data ??= [];
-        if (message.bins) {
-            const { bins } = message;
-            let { data } = message;
-            for (const ibin of bins) {
-                const len_buf = data[ibin];
-                data[ibin] = buffer.subarray(offset, offset + len_buf);
-                offset += len_buf;
-            }
-        }
-        if (message.error)
-            message.error = Object.assign(new Error(), message.error);
-        return message;
-    }
-    static pack({ id, func, data = [], done, error }) {
-        let data_ = new Array(data.length);
-        let bins = [];
-        let bufs = [];
-        for (let i = 0; i < data.length; i++) {
-            const item = data[i];
-            if (item instanceof Uint8Array) {
-                bins.push(i);
-                bufs.push(item);
-                data_[i] = item.length;
-            }
-            else
-                data_[i] = item;
-        }
-        const data_json = {
-            id,
-            ...func ? { func } : {},
-            ...done ? { done } : {},
-            ...error ? { error } : {},
-            ...data_.length ? { data: data_ } : {},
-            ...bins.length ? { bins } : {},
-        };
-        // 有可能 data_json 含有循环引用导致 JSON.stringify 报错
-        const str_json = 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]);
-    }
     /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
         作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
     constructor({ url, funcs, print, verbose, websocket, keeper, on_error, } = {}) {
@@ -668,9 +621,8 @@ export class Remote {
             console.log('remote.send:', message);
         try {
             await this.connect(websocket);
-            if (!message.id)
-                message.id = genid();
-            (websocket || this.lwebsocket.resource).send(Remote.pack(message));
+            message[message_symbol] = true;
+            (websocket || this.lwebsocket.resource).send(pack(message));
         }
         catch (error) {
             if (message.id)
@@ -684,9 +636,10 @@ export class Remote {
         使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214
         这个方法一般不会抛出错误，也不需要 await，一般在 websocket on_message 时使用 */
     async handle(data, websocket) {
+        check(data[0] === 0xcc, 'message 格式错误');
         let message;
         try {
-            message = Remote.parse(data);
+            message = parse(data);
         }
         catch (error) {
             this.on_error(error);

package/package.json

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

package/process.js

@@ -36,6 +36,7 @@ input, stdin = Boolean(input), stdout = !detached, stderr = stdout, print = true
             ...envs
         });
     // --- 处理 stdio: 将 stdio 中的 true, false, string 转换为对应的 node.js stdio 值
+    check(stdout !== 'ignore' || stderr !== 'ignore');
     if (detached)
         check([stdin, stdout, stderr].every(io => io !== true), '调用 start 启动 detached 进程时 stdio 不能为 true (pipe)');
     let opened_handles = [];

package/prototype.browser.d.ts

@@ -77,10 +77,17 @@ declare global {
             indent: number;
             text: string;
         };
-        /** 将 string 根据首个找到的 splitter 拆分 string 为两个部分（必须包含 splitter，否则抛出错误）
+        /** 将 string 根据首个找到的 splitter 拆分 string 为两个部分
             - spitter: 不会包含在结果中
-            - last?: `false` 为 true 时从后往前找 splitter */
-        split2(this: string, splitter: string, last?: boolean): [string, string];
+            - options?:
+                - last?: `false` 为 true 时从后往前找 splitter
+                - optional?: `false`
+                    - false: 必须包含 splitter，否则抛出错误
+                    - true: 允许不存在 splitter, 返回的数组为 [this] */
+        split2(this: string, splitter: string, options?: {
+            last?: boolean;
+            optional?: boolean;
+        }): [string, string?];
         space(this: string): string;
         /** 返回去掉 prefix 开头的字符串
             - validate?: `false` 传 true 时确保字符串以 prefix 开头（失败时抛出错误） */
@@ -99,12 +106,14 @@ declare global {
         /** 从 search 字符串出现的位置开始截取到最后
             - options?:
                 - include?: `false` 传 true 时包括 search 部分
-                - last?: `false` true 时从最后一次出现的地方开始截取，否则默认从第一次出现的地方开始截取 */
+                - last?: `false` true 时从最后一次出现的地方开始截取，否则默认从第一次出现的地方开始截取
+                - optional?: `false` 传 true 时允许不存在 search，此时返回完整的 this */
         slice_from(this: string, search: string, options?: SliceOptions): string;
         /** 从 search 字符串出现的位置开始截断，去掉尾部
             - options?:
                 - include?: `false` 传 true 时包括 search 部分
-                - last?: `false` true 时截取到最后一次出现的地方，否则默认截取到第一次出现的地方 */
+                - last?: `false` 传 true 时截取到最后一次出现的地方，否则默认截取到第一次出现的地方
+                - optional?: `false` 传 true 时允许不存在 search，此时返回完整的 this */
         slice_to(this: string, search: string, options?: SliceOptions): string;
         /** 等价于 .endsWith('/') */
         isdir: boolean;
@@ -192,15 +201,19 @@ declare global {
     interface Set<T> {
         map<TResult>(mapper: (value: T, index: number) => TResult): TResult[];
     }
+    interface Uint8Array<TArrayBuffer extends ArrayBufferLike> {
+        dataview: DataView<TArrayBuffer>;
+    }
 }
 interface SliceOptions {
     include?: boolean;
     last?: boolean;
+    optional?: boolean;
 }
 export declare const emoji_regex: RegExp;
 export declare const noop: () => void;
 export declare const ident: <T>(x: T) => T;
-export declare const build_mapper: <TObj>(key: keyof TObj) => (obj: TObj) => TObj[keyof TObj];
+export declare const build_mapper: <TObj, TKey extends keyof TObj>(key: TKey) => (obj: TObj) => TObj[TKey];
 export type Mapper<TObj = any, TKey extends keyof TObj = keyof TObj> = (obj: TObj) => TObj[TKey];
 /** value 不为 null 或 undefined */
 export declare const not_empty: (value: any) => boolean;

package/prototype.browser.js

@@ -265,10 +265,13 @@ Object.defineProperties(String.prototype, {
                 text: this.slice(i)
             };
         },
-        split2(splitter, last = false) {
+        split2(splitter, { last = false, optional = false } = {}) {
             const isplitter = last ? this.lastIndexOf(splitter) : this.indexOf(splitter);
             if (isplitter === -1)
-                throw new Error(`字符串: ${this} 必须包含 splitter: ${splitter}`);
+                if (optional)
+                    return [this];
+                else
+                    throw new Error(`字符串: ${this} 必须包含 splitter: ${splitter}`);
             return [this.slice(0, isplitter), this.slice(isplitter + splitter.length)];
         },
         strip_start(prefix, validate) {
@@ -293,17 +296,23 @@ Object.defineProperties(String.prototype, {
         ensure_end(suffix = '\n') {
             return this.endsWith(suffix) ? this : this + suffix;
         },
-        slice_from(search, { include = false, last = false } = {}) {
+        slice_from(search, { include = false, last = false, optional = false } = {}) {
             const i = last ? this.lastIndexOf(search) : this.indexOf(search);
             if (i === -1)
-                throw new Error(`slice_from 在字符串 ${this} 中找不到 search: ${search}`);
+                if (optional)
+                    return this;
+                else
+                    throw new Error(`slice_from 在字符串 ${this} 中找不到 search: ${search}`);
             else
                 return this.slice(include ? i : i + search.length);
         },
-        slice_to(search, { include = false, last = false } = {}) {
+        slice_to(search, { include = false, last = false, optional = false } = {}) {
             const i = last ? this.lastIndexOf(search) : this.indexOf(search);
             if (i === -1)
-                throw new Error(`slice_to 在字符串 ${this} 中找不到 search: ${search}`);
+                if (optional)
+                    return this;
+                else
+                    throw new Error(`slice_to 在字符串 ${this} 中找不到 search: ${search}`);
             else
                 return this.slice(0, include ? i + search.length : i);
         },
@@ -561,6 +570,11 @@ Object.defineProperties(Set.prototype, to_method_property_descriptors({
         return Array.from(this, mapfn);
     }
 }));
+Object.defineProperties(Uint8Array.prototype, to_getter_property_descriptors({
+    dataview() {
+        return new DataView(this.buffer, this.byteOffset, this.byteLength);
+    }
+}));
 export function to_json(obj, replacer) {
     return JSON.stringify(obj, replacer, 4) + '\n';
 }

package/prototype.d.ts

@@ -94,10 +94,17 @@ declare global {
             indent: number;
             text: string;
         };
-        /** 将 string 根据首个找到的 splitter 拆分 string 为两个部分（必须包含 splitter，否则抛出错误）
+        /** 将 string 根据首个找到的 splitter 拆分 string 为两个部分
             - spitter: 不会包含在结果中
-            - last?: `false` 为 true 时从后往前找 splitter */
-        split2(this: string, splitter: string, last?: boolean): [string, string];
+            - options?:
+                - last?: `false` 为 true 时从后往前找 splitter
+                - optional?: `false`
+                    - false: 必须包含 splitter，否则抛出错误
+                    - true: 允许不存在 splitter, 返回的数组为 [this] */
+        split2(this: string, splitter: string, options?: {
+            last?: boolean;
+            optional?: boolean;
+        }): [string, string?];
         to_base64(this: string): string;
         /** - buffer: `false` 直接返回 Buffer */
         decode_base64(this: string): string;
@@ -121,12 +128,14 @@ declare global {
         /** 从 search 字符串出现的位置开始截取到最后
             - options?:
                 - include?: `false` 传 true 时包括 search 部分
-                - last?: `false` true 时从最后一次出现的地方开始截取，否则默认从第一次出现的地方开始截取 */
+                - last?: `false` true 时从最后一次出现的地方开始截取，否则默认从第一次出现的地方开始截取
+                - optional?: `false` 传 true 时允许不存在 search，此时返回完整的 this */
         slice_from(this: string, search: string, options?: SliceOptions): string;
         /** 从 search 字符串出现的位置开始截断，去掉尾部
             - options?:
                 - include?: `false` 传 true 时包括 search 部分
-                - last?: `false` true 时截取到最后一次出现的地方，否则默认截取到第一次出现的地方 */
+                - last?: `false` 传 true 时截取到最后一次出现的地方，否则默认截取到第一次出现的地方
+                - optional?: `false` 传 true 时允许不存在 search，此时返回完整的 this */
         slice_to(this: string, search: string, options?: SliceOptions): string;
         /** 等价于 .endsWith('/') */
         isdir: boolean;
@@ -222,15 +231,19 @@ declare global {
     interface Set<T> {
         map<TResult>(mapper: (value: T, index: number) => TResult): TResult[];
     }
+    interface Uint8Array<TArrayBuffer extends ArrayBufferLike> {
+        dataview: DataView<TArrayBuffer>;
+    }
 }
 interface SliceOptions {
     include?: boolean;
     last?: boolean;
+    optional?: boolean;
 }
 export declare const emoji_regex: RegExp;
 export declare const noop: () => void;
 export declare const ident: <T>(x: T) => T;
-export declare const build_mapper: <TObj>(key: keyof TObj) => (obj: TObj) => TObj[keyof TObj];
+export declare const build_mapper: <TObj, TKey extends keyof TObj>(key: TKey) => (obj: TObj) => TObj[TKey];
 export type Mapper<TObj = any, TKey extends keyof TObj = keyof TObj> = (obj: TObj) => TObj[TKey];
 /** value 不为 null 或 undefined */
 export declare const not_empty: (value: any) => boolean;

package/prototype.js

@@ -272,10 +272,13 @@ if (!globalThis.my_prototype_defined) {
                     text: this.slice(i)
                 };
             },
-            split2(splitter, last = false) {
+            split2(splitter, { last = false, optional = false } = {}) {
                 const isplitter = last ? this.lastIndexOf(splitter) : this.indexOf(splitter);
                 if (isplitter === -1)
-                    throw new Error(`字符串: ${this} 必须包含 splitter: ${splitter}`);
+                    if (optional)
+                        return [this];
+                    else
+                        throw new Error(`字符串: ${this} 必须包含 splitter: ${splitter}`);
                 return [this.slice(0, isplitter), this.slice(isplitter + splitter.length)];
             },
             trim_doc_comment() {
@@ -315,17 +318,23 @@ if (!globalThis.my_prototype_defined) {
             ensure_end(suffix = '\n') {
                 return this.endsWith(suffix) ? this : this + suffix;
             },
-            slice_from(search, { include = false, last = false } = {}) {
+            slice_from(search, { include = false, last = false, optional = false } = {}) {
                 const i = last ? this.lastIndexOf(search) : this.indexOf(search);
                 if (i === -1)
-                    throw new Error(`slice_from 在字符串 ${this} 中找不到 search: ${search}`);
+                    if (optional)
+                        return this;
+                    else
+                        throw new Error(`slice_from 在字符串 ${this} 中找不到 search: ${search}`);
                 else
                     return this.slice(include ? i : i + search.length);
             },
-            slice_to(search, { include = false, last = false } = {}) {
+            slice_to(search, { include = false, last = false, optional = false } = {}) {
                 const i = last ? this.lastIndexOf(search) : this.indexOf(search);
                 if (i === -1)
-                    throw new Error(`slice_to 在字符串 ${this} 中找不到 search: ${search}`);
+                    if (optional)
+                        return this;
+                    else
+                        throw new Error(`slice_to 在字符串 ${this} 中找不到 search: ${search}`);
                 else
                     return this.slice(0, include ? i + search.length : i);
             },
@@ -625,6 +634,11 @@ if (!globalThis.my_prototype_defined) {
             return Array.from(this, mapfn);
         }
     }));
+    Object.defineProperties(Uint8Array.prototype, to_getter_property_descriptors({
+        dataview() {
+            return new DataView(this.buffer, this.byteOffset, this.byteLength);
+        }
+    }));
 }
 export function to_json(obj, replacer) {
     return JSON.stringify(obj, replacer, 4) + '\n';

package/server.d.ts

@@ -59,12 +59,11 @@ export declare class Server {
     stdio_subscribable?: boolean;
     stdio_subscribers: (((chunk: Uint8Array | string) => Promise<void>) & {
         id: number;
-        closer: (event: any) => void;
+        close: () => void;
     })[];
     /** 原始 process.stdout.write 函数 bind 后的备份 */
     stdout_write: Function;
     stderr_write: Function;
-    url_width: 52;
     constructor({ name, print, http, http2, http_port, http2_port, fpd_certs, default_hostnames, remote, funcs, stdio_subscribable, log_date }: {
         name: string;
         print?: boolean | {
@@ -153,6 +152,7 @@ export declare class Server {
         assets_root?: string;
         sea?: boolean;
     }): Promise<string>;
+    set_content_type(response: Koa.Response, fext: string): void;
     /** - range: 取值为逗号分割的多个可用端口或端口区间 (不能含有空格，包含区间右值)，比如：`8321,8322,8300-8310,11000-11999
         - reverse?: `false` 在 range 内从后往前尝试 */
     static get_available_port(range: string, reverse?: boolean): Promise<number>;

package/server.js

@@ -14,7 +14,7 @@ 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 } from "./utils.js";
+import { inspect, check, range_to_numbers, encode, filter_keys, filter_values, consume_stream, colored, url_width } from "./utils.js";
 import { flist, fread, fstat } from "./file.js";
 import { exe_nodejs, sea } from "./process.js";
 // ------------ my server
@@ -64,7 +64,6 @@ export class Server {
     /** 原始 process.stdout.write 函数 bind 后的备份 */
     stdout_write;
     stderr_write;
-    url_width = 52;
     constructor({ name, print, http, http2, http_port, http2_port, fpd_certs, default_hostnames, remote, funcs, stdio_subscribable, log_date }) {
         this.name = name;
         if (print !== undefined) {
@@ -187,20 +186,20 @@ export class Server {
                         };
                         // 让后续可以通过 unsubscribe_stdio 取消订阅
                         subscriber.id = id;
-                        const closer = subscriber.closer = () => {
+                        const close = subscriber.close = () => {
                             const length = this.stdio_subscribers.length;
                             const stdio_subscribers_ = this.stdio_subscribers.filter(s => s !== subscriber);
                             if (stdio_subscribers_.length !== length)
                                 this.stdio_subscribers = stdio_subscribers_;
                         };
                         this.stdio_subscribers.push(subscriber);
-                        websocket.addEventListener('close', closer, { once: true });
+                        websocket.addEventListener('close', close, { once: true });
                     },
                     /** 主动取消订阅，需要清理 stdio listener, websocket close lisener */
                     unsubscribe_stdio: ({ data: [id] }, websocket) => {
                         this.stdio_subscribers = this.stdio_subscribers.filter(s => {
                             if (s.id === id) {
-                                websocket.removeEventListener('close', s.closer);
+                                websocket.removeEventListener('close', s.close);
                                 return false;
                             }
                             else
@@ -286,7 +285,7 @@ export class Server {
                 host +
                 // path
                 url;
-            s = s.pad(this.url_width);
+            s = s.pad(url_width);
             // ip
             s += `  <-  ${request.socket.remoteAddress.strip_if_start('::ffff:')}`;
             // ua
@@ -405,14 +404,14 @@ export class Server {
                 ? path
                 : path.yellow;
         // range
-        let range = headers.range;
+        const range = headers.range;
         if (headers.range) {
             let [, start, end] = /(\d*)-(\d*)/.exec(range) || [];
             if (start)
                 start = Number(start).to_fsize_str();
             if (end)
                 end = Number(end).to_fsize_str();
-            s += ` (${start} - ${end || ''})`;
+            s += ` (${start} - ${end || ''})`.limit(18);
         }
         s += ' ';
         // queries
@@ -422,7 +421,7 @@ export class Server {
                 .strip_if_end('\n');
             s += ' ';
         }
-        s = s.pad(this.url_width);
+        s = s.pad(url_width);
         // ip
         s += `  <-  ${ip.strip_if_start('::ffff:')}`;
         // ua
@@ -430,8 +429,8 @@ export class Server {
         if (ua)
             s += `／${ua}`;
         // body
-        if (body && Object.keys(body).length)
-            s += '\n' + inspect(body).replace('[Object: null prototype] ', '');
+        if (body)
+            s += '\n' + inspect(body);
         // 打印日志
         console.log(s);
     }
@@ -653,12 +652,8 @@ export class Server {
             response.set('last-modified', last_modified_str);
         if (download)
             response.set('content-disposition', `attachment; filename="${encodeURIComponent(fp.fname)}"`);
-        if (!response.get('content-type')) {
-            const { fext } = fp;
-            response.set('content-type', (Server.js_exts.has(fext)
-                ? 'text/javascript; chatset=utf-8'
-                : get_content_type(`file.${fext}`) || 'application/octet-stream'));
-        }
+        if (!response.get('content-type'))
+            this.set_content_type(response, fp.fext);
         const modified_since_str = request.get('if-modified-since');
         if ((method === 'GET' || method === 'HEAD') && modified_since_str === last_modified_str) {
             response.status = 304;
@@ -703,6 +698,11 @@ export class Server {
         }
         return fp;
     }
+    set_content_type(response, fext) {
+        response.set('content-type', (Server.js_exts.has(fext)
+            ? 'text/javascript; chatset=utf-8'
+            : get_content_type(`file.${fext}`) || 'application/octet-stream'));
+    }
     /** - range: 取值为逗号分割的多个可用端口或端口区间 (不能含有空格，包含区间右值)，比如：`8321,8322,8300-8310,11000-11999
         - reverse?: `false` 在 range 内从后往前尝试 */
     static async get_available_port(range, reverse = false) {

package/utils.browser.d.ts

@@ -16,7 +16,9 @@ export declare function unique<TObj>(iterable: TObj[] | Iterable<TObj>, mapper?:
 export declare function seq<T = number>(n: number, generator?: (index: number) => T): T[];
 /** 将 keys, values 数组按对应的顺序组合成一个对象 */
 export declare function zip_object<TValue>(keys: (string | number)[], values: TValue[]): Record<string, TValue>;
-/** 过滤对象中的 values, 返回新对象 */
+/** 过滤对象中的 values, 返回新对象
+    - obj
+    - filter?: `not_empty` */
 export declare function filter_values<TObj extends Record<string, any>>(obj: TObj, filter?: (value: TObj[string]) => any): TObj;
 export declare function delay(milliseconds: number, { signal }?: {
     signal?: AbortSignal;
@@ -78,6 +80,7 @@ export declare class Lock<TResource = void> {
 export declare function pause(milliseconds?: number): Promise<void>;
 /** 将字符串简单的编码为 utf-8 的 buffer (Uint8Array)。高频使用或者在流式处理时，考虑使用 TextEncoder 的 encodeInto 方法 */
 export declare function encode(str: string): Uint8Array<ArrayBufferLike>;
+export declare function encode_into(str: string, buf: Uint8Array): TextEncoderEncodeIntoResult;
 /** 将 utf-8 buffer (Uint8Array) 简单的解码为 string。
     在流式处理 (buffer 可能不完整) 时，应使用独立的 TextDecoder 实例调用 decode(buffer, { stream: true }) */
 export declare function decode(buffer: Uint8Array): string;
@@ -90,6 +93,7 @@ export declare function vercmp(l: string, r: string, loose?: boolean): number;
 /** 过滤符合 pattern 的行 */
 export declare function grep(str: string, pattern: string | RegExp): string;
 /** 模糊过滤字符串列表或对象列表，常用于根据用户输入补全或搜索过滤
+    如果有完全匹配的，只返回那一项的数组
     - query: 查询字符串，要求为全小写
     - list: 要过滤的列表
     - list_lower?: 要过滤的列表对应的全小写字符串列表形式，传入时可复用缓存，加快搜索速度 */
@@ -127,3 +131,5 @@ export declare class Timer {
     getstr_and_reset(parenthesis?: boolean): string;
 }
 export declare function lowercase_first_letter(str: string): string;
+/** 大于 n 的最小的 2 的幂次 */
+export declare function ceil2(n: number): number;

package/utils.browser.js

@@ -54,7 +54,9 @@ export function zip_object(keys, values) {
         return obj;
     }, {});
 }
-/** 过滤对象中的 values, 返回新对象 */
+/** 过滤对象中的 values, 返回新对象
+    - obj
+    - filter?: `not_empty` */
 export function filter_values(obj, filter = not_empty) {
     return Object.fromEntries(Object.entries(obj)
         .filter(([, value]) => filter(value)));
@@ -229,6 +231,10 @@ let encoder = new TextEncoder();
 export function encode(str) {
     return encoder.encode(str);
 }
+export function encode_into(str, buf) {
+    // 这个是直接用 v8 String::WriteUtf8 最高效的方法了
+    return encoder.encodeInto(str, buf);
+}
 let decoder = new TextDecoder();
 /** 将 utf-8 buffer (Uint8Array) 简单的解码为 string。
     在流式处理 (buffer 可能不完整) 时，应使用独立的 TextDecoder 实例调用 decode(buffer, { stream: true }) */
@@ -271,6 +277,7 @@ export function grep(str, pattern) {
         .join_lines();
 }
 /** 模糊过滤字符串列表或对象列表，常用于根据用户输入补全或搜索过滤
+    如果有完全匹配的，只返回那一项的数组
     - query: 查询字符串，要求为全小写
     - list: 要过滤的列表
     - list_lower?: 要过滤的列表对应的全小写字符串列表形式，传入时可复用缓存，加快搜索速度 */
@@ -281,11 +288,14 @@ export function fuzzyfilter(query, list, mapper = ident, list_lower, single_char
         mapper = build_mapper(mapper);
     mapper ??= ident;
     list_lower ??= list.map(item => mapper(item).toLowerCase());
+    const query_lower = query.toLowerCase();
+    let ifullmatch;
+    if ((ifullmatch = list_lower.indexOf(query_lower)) !== -1)
+        return [list[ifullmatch]];
     if (single_char_startswith && query.length === 1) {
         const c = query[0];
         return list.filter((_, i) => list_lower[i].startsWith(c));
     }
-    const query_lower = query.toLowerCase();
     return list.filter((_, i) => {
         const str_lower = list_lower[i];
         let j = 0;
@@ -401,4 +411,11 @@ export class Timer {
 export function lowercase_first_letter(str) {
     return str[0].toLowerCase() + str.slice(1);
 }
+/** 大于 n 的最小的 2 的幂次 */
+export function ceil2(n) {
+    let power = 1;
+    for (; power <= n; power <<= 1)
+        ;
+    return power;
+}
 //# sourceMappingURL=utils.browser.js.map