@anjianshi/utils 2.7.0 → 2.8.1

package/lang/object.js

@@ -0,0 +1,41 @@
+/**
+ * 对两个对象进行浅比较
+ * 代码取自 react-addons-shallow-compare 包
+ */
+export function shallowEqual(objA, objB) {
+    if (is(objA, objB))
+        return true;
+    if (!isObject(objA) || !isObject(objB))
+        return false;
+    const keysA = Object.keys(objA);
+    const keysB = Object.keys(objB);
+    if (keysA.length !== keysB.length)
+        return false;
+    // eslint-disable-next-line @typescript-eslint/prefer-for-of
+    for (let i = 0; i < keysA.length; i++) {
+        const key = keysA[i];
+        // eslint-disable-next-line prefer-object-has-own
+        if (!Object.prototype.hasOwnProperty.call(objB, key) || !is(objA[key], objB[key]))
+            return false;
+    }
+    return true;
+}
+function is(x, y) {
+    if (x === y)
+        return x !== 0 || y !== 0 || 1 / x === 1 / y;
+    else
+        return x !== x && y !== y; // eslint-disable-line no-self-compare
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * 获取对象的方法，并将它的 this 锁定在原对象
+ *
+ * const method = getBoundMethod(object, 'someMethod')
+ * method(1,2,3) // 不用担心 this 改变
+ */
+export function getBoundMethod(object, key) {
+    const property = object[key];
+    return (typeof property === 'function' ? property.bind(object) : property);
+}

package/lang/random.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 返回随机数，包含 min 和 max
+ */
+export declare function getRandomInt(min: number, max: number): number;
+/**
+ * 返回随机字符串
+ */
+export declare function getRandomString(length?: number, seed?: string): string;
+/**
+ * 从给定的选择中随机选中一项
+ * 如果数组为空，会返回 undefined
+ */
+export declare function choiceRandom<T>(choices: T[]): T | undefined;

package/lang/random.js

@@ -0,0 +1,24 @@
+/**
+ * 返回随机数，包含 min 和 max
+ */
+export function getRandomInt(min, max) {
+    const minCeiled = Math.ceil(min);
+    const maxFloored = Math.floor(max);
+    return Math.floor(Math.random() * (maxFloored - minCeiled + 1) + minCeiled);
+}
+/**
+ * 返回随机字符串
+ */
+export function getRandomString(length = 6, seed = '0123456789abcdefghijklmnopqrstuvwxyz') {
+    let result = '';
+    while (result.length < length)
+        result += seed[getRandomInt(0, seed.length - 1)];
+    return result;
+}
+/**
+ * 从给定的选择中随机选中一项
+ * 如果数组为空，会返回 undefined
+ */
+export function choiceRandom(choices) {
+    return choices[getRandomInt(0, choices.length - 1)];
+}

package/lang/string.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 将数字字符串化，并在左侧填充 0 直到达到 length 参数指定的长度
+ * 若数字本身达到或超过此长度，则不填充
+ */
+export declare function zfill(num: number, length?: number): string;
+export declare function keywordCompare(keyword: string, target: string): boolean;
+export declare function numericCompare(a: string, b: string): number;
+/**
+ * 字符串解析成整数，补充安全措施：
+ * 1. 默认设置 radix 为 10，无需再手动指定
+ * 2. 支持指定 fallback，当解析出来的数字是 NaN 时返回这个值
+ */
+export declare function safeParseInt(value: string | number, fallback?: number, redix?: number): number;
+/**
+ * 字符串解析成浮点数；若解析结果是 NaN，返回 fallback
+ */
+export declare function safeParseFloat(value: string | number, fallback: number): number;
+/**
+ * 返回人类可读的文件尺寸
+ * 来自：https://stackoverflow.com/a/14919494
+ *
+ * si: true 则使用 1000 进制，否则 1024 进制（默认 false）
+ * dp: 保留几位小数
+ */
+export declare function readableSize(bytes: number, si?: boolean, dp?: number): string;
+/**
+ * 解析 JSON，失败时不抛出异常，而是返回 undefined
+ */
+export declare function safeParseJSON<T>(json: string): T | undefined;

package/lang/string.js

@@ -0,0 +1,92 @@
+/**
+ * 字符串处理相关函数
+ */
+import escapeRegExp from 'lodash/escapeRegExp.js';
+import padStart from 'lodash/padStart.js';
+/**
+ * 将数字字符串化，并在左侧填充 0 直到达到 length 参数指定的长度
+ * 若数字本身达到或超过此长度，则不填充
+ */
+export function zfill(num, length = 2) {
+    return padStart(String(num), length, '0');
+}
+/**
+ * 执行关键词匹配
+ * 成功返回 true；失败返回 false
+ */
+const kwCache = {}; // 避免大量重复构建正则表达式影响性能
+export function keywordCompare(keyword, target) {
+    if (!keyword)
+        return true;
+    if (!(keyword in kwCache)) {
+        const regStr = keyword.split('').map(escapeRegExp).join('.*');
+        kwCache[keyword] = new RegExp(regStr, 'i');
+    }
+    return kwCache[keyword].test(target);
+}
+/**
+ * 对两个字符串进行排序，支持处理逻辑上的数字。
+ * 两个字符串都完全由数字组成，且都不以 0 开头时，以数字大小排序；否则以字符串形式排序。
+ *
+ * 以 0 开头是特例，例如 019 和 12 两个字符串，按直觉还是应该 019 在前面，毕竟本质还是字符串排序。
+ *
+ * "123" "456"             数字排序
+ * "123你好" "133我好"     字符串排序
+ * "019" "12"              字符串排序
+ */
+const _pattern = /^[1-9][0-9]*$/;
+export function numericCompare(a, b) {
+    if (_pattern.exec(a) && _pattern.exec(b))
+        return parseInt(a, 10) - parseInt(b, 10);
+    return a.localeCompare(b);
+}
+/**
+ * 字符串解析成整数，补充安全措施：
+ * 1. 默认设置 radix 为 10，无需再手动指定
+ * 2. 支持指定 fallback，当解析出来的数字是 NaN 时返回这个值
+ */
+export function safeParseInt(value, fallback, redix = 10) {
+    const raw = parseInt(String(value), redix);
+    return isFinite(raw) ? raw : (fallback ?? raw);
+}
+/**
+ * 字符串解析成浮点数；若解析结果是 NaN，返回 fallback
+ */
+export function safeParseFloat(value, fallback) {
+    const raw = parseFloat(String(value));
+    return isFinite(raw) ? raw : fallback;
+}
+/**
+ * 返回人类可读的文件尺寸
+ * 来自：https://stackoverflow.com/a/14919494
+ *
+ * si: true 则使用 1000 进制，否则 1024 进制（默认 false）
+ * dp: 保留几位小数
+ */
+export function readableSize(bytes, si = false, dp = 1) {
+    const thresh = si ? 1000 : 1024;
+    if (Math.abs(bytes) < thresh)
+        return bytes.toString() + ' B';
+    const units = si
+        ? ['kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
+        : ['KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
+    let u = -1;
+    const r = 10 ** dp;
+    do {
+        bytes /= thresh;
+        ++u;
+    } while (Math.round(Math.abs(bytes) * r) / r >= thresh && u < units.length - 1);
+    return `${bytes.toFixed(dp)} ${units[u]}`;
+}
+/**
+ * 解析 JSON，失败时不抛出异常，而是返回 undefined
+ */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function safeParseJSON(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (e) {
+        return undefined;
+    }
+}

package/lang/time.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 时间处理相关函数
+ */
+/**
+ * 返回指定时间长度的 毫秒数
+ */
+export declare function daysMS(n: number): number;
+export declare function hoursMS(n: number): number;
+export declare function minutesMS(n: number): number;
+export declare function secondsMS(n: number): number;

package/lang/time.js

@@ -0,0 +1,18 @@
+/**
+ * 时间处理相关函数
+ */
+/**
+ * 返回指定时间长度的 毫秒数
+ */
+export function daysMS(n) {
+    return hoursMS(n * 24);
+}
+export function hoursMS(n) {
+    return minutesMS(n * 60);
+}
+export function minutesMS(n) {
+    return secondsMS(n * 60);
+}
+export function secondsMS(n) {
+    return n * 1000;
+}

package/{src/lang/types.ts → lang/types.d.ts}

@@ -1,7 +1,6 @@
 /**
  * 对类型系统的辅助、补充
  */
-
 /**
  * 解决 TypeScript 中，数组字面量 [1, 'a'] 无法自动识别为 tuple 的问题
  *
@@ -12,22 +11,17 @@
  * https://github.com/microsoft/TypeScript/issues/27179
  * https://github.com/microsoft/TypeScript/issues/16656
  */
-export function tuple<T extends unknown[]>(...elements: T) {
-  return elements
-}
-
+export declare function tuple<T extends unknown[]>(...elements: T): T;
 /** 将一个对象中的指定 key 设为必须的 */
-export type RequiredFields<T, K extends keyof T> = Omit<T, K> & Pick<Required<T>, K>
-
+export type RequiredFields<T, K extends keyof T> = Omit<T, K> & Pick<Required<T>, K>;
 /** 将一个对象中的指定 key 设为非必须的 */
-export type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
-
+export type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 /** 用 ReplaceT 中的字段定义代替 T 中的 */
-export type ReplaceFields<T, ReplaceT> = Omit<T, keyof ReplaceT> & ReplaceT
-
+export type ReplaceFields<T, ReplaceT> = Omit<T, keyof ReplaceT> & ReplaceT;
 /** 获取一个对象所有 value 的集合 */
-export type ValueOf<T> = T extends { [_ in keyof T]: infer U } ? U : never
-
+export type ValueOf<T> = T extends {
+    [_ in keyof T]: infer U;
+} ? U : never;
 /**
  * 获取指定类型的 key 的集合
  * 可以解决 keyof 无法正确获取继承了 plain object interface 的类型的 key 的问题
@@ -38,46 +32,32 @@ export type ValueOf<T> = T extends { [_ in keyof T]: infer U } ? U : never
  * KnownKeys<MyType>     // 'a' | 'b'
  */
 export type KnownKeys<T> = ValueOf<{
-  [K in keyof T]: string extends K ? never : number extends K ? never : K
-}>
-
+    [K in keyof T]: string extends K ? never : number extends K ? never : K;
+}>;
 /** 排除对象中指定类型的项目 */
-export type ExcludePropertiesOfType<T, ExcludeValueT> = Pick<
-  T,
-  { [K in keyof T]: T[K] extends ExcludeValueT ? never : K }[keyof T]
->
-
+export type ExcludePropertiesOfType<T, ExcludeValueT> = Pick<T, {
+    [K in keyof T]: T[K] extends ExcludeValueT ? never : K;
+}[keyof T]>;
 /**
  * 生成不包含指定 key 的类型
  * 与 Omit<T, Keys> 的区别是
  */
-export type ExcludeKeys<T, ExcludeKeys> = Pick<
-  T,
-  { [K in keyof T]: K extends ExcludeKeys ? never : K }[keyof T]
->
-
+export type ExcludeKeys<T, ExcludeKeys> = Pick<T, {
+    [K in keyof T]: K extends ExcludeKeys ? never : K;
+}[keyof T]>;
 /** 排除对象的方法（仅保留属性） */
-// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>
-
+export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>;
 /**
  * 确认变量是否有值
  * 注意：空字符串和数字 0 也会判定为没有值
  */
-function truthy(
-  value: string | number | boolean | null | undefined,
-): value is string | number | true
-function truthy<T>(
-  value: T | string | number | boolean | null | undefined,
-): value is T | string | number | true
-function truthy<T>(value: T | string | number | boolean | null | undefined) {
-  return value !== null && value !== undefined && value !== '' && value !== 0 && value !== false
-}
-export { truthy }
-
+declare function truthy(value: string | number | boolean | null | undefined): value is string | number | true;
+declare function truthy<T>(value: T | string | number | boolean | null | undefined): value is T | string | number | true;
+export { truthy };
 /** 定义 JSON 数据 */
-export type JSONData = number | boolean | string | null | JSONData[] | { [key: string]: JSONData }
-
+export type JSONData = number | boolean | string | null | JSONData[] | {
+    [key: string]: JSONData;
+};
 /**
  * 有些场景不适合用 undefined 判断一个变量是否被赋值（例如它允许被赋值成 undefined）
  * 此时可以用这个 symbol 来做判断。
@@ -85,4 +65,4 @@ export type JSONData = number | boolean | string | null | JSONData[] | { [key: s
  * if (value === noValue) console.log('未赋值')
  * else console.log('已赋值', value)
  */
-export const noValue = Symbol('no-value')
+export declare const noValue: unique symbol;

package/lang/types.js

@@ -0,0 +1,28 @@
+/**
+ * 对类型系统的辅助、补充
+ */
+/**
+ * 解决 TypeScript 中，数组字面量 [1, 'a'] 无法自动识别为 tuple 的问题
+ *
+ * 使用方法：
+ * const t = tuple(1, 'a')    // 类型会识别为 [1, 'a'] 而不是 (number | string)[]
+ *
+ * 待官方提供语言层面的支持
+ * https://github.com/microsoft/TypeScript/issues/27179
+ * https://github.com/microsoft/TypeScript/issues/16656
+ */
+export function tuple(...elements) {
+    return elements;
+}
+function truthy(value) {
+    return value !== null && value !== undefined && value !== '' && value !== 0 && value !== false;
+}
+export { truthy };
+/**
+ * 有些场景不适合用 undefined 判断一个变量是否被赋值（例如它允许被赋值成 undefined）
+ * 此时可以用这个 symbol 来做判断。
+ *
+ * if (value === noValue) console.log('未赋值')
+ * else console.log('已赋值', value)
+ */
+export const noValue = Symbol('no-value');

package/logging/adapt.d.ts

@@ -0,0 +1,10 @@
+import { type Logger } from './index.js';
+interface Debug {
+    enable: (namespaces: string) => void;
+    log: (...args: any[]) => any;
+}
+/**
+ * 适配 debug package
+ */
+export declare function adaptDebugLib(debugLib: Debug, enable?: string, logger?: Logger): void;
+export {};

package/logging/adapt.js

@@ -0,0 +1,43 @@
+import { getLogger } from './index.js';
+/**
+ * 适配 debug package
+ */
+export function adaptDebugLib(debugLib, enable = '', logger) {
+    // 不在 localStorage 里记录 debugLib enable 状态，
+    // 以解决 web worker 里读不到 localStorage 而无法启用 debugLib 日志的问题
+    const emulate = {
+        storage: {
+            data: {},
+            getItem(name) {
+                return emulate.storage.data[name];
+            },
+            setItem(name, value) {
+                emulate.storage.data[name] = value;
+            },
+            removeItem(name) {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                delete emulate.storage.data[name];
+            },
+        },
+        save(namespaces) {
+            if (namespaces)
+                emulate.storage.setItem('debug', namespaces);
+            else
+                emulate.storage.removeItem('debug');
+        },
+        load() {
+            return emulate.storage.getItem('debug');
+        },
+    };
+    Object.assign(debugLib, emulate);
+    // 将 debugLib 日志转发给 logger
+    if (!logger)
+        logger = getLogger('3rd-library');
+    debugLib.log = logger.debug.bind(logger);
+    if (enable) {
+        // 有些库（例如 prisma）重新实现了自己的 debug 库，且模仿 debug 也读取 DEBUG 环境变量。
+        // 这里除了设置 debug 库，顺便也适配这些遵循 debug 库模式的自定义库。
+        process.env.DEBUG = enable;
+        debugLib.enable(enable);
+    }
+}

package/logging/formatters.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 日志常用数据的格式化函数
+ */
+import { type LogInfo } from './index.js';
+declare const formatters: {
+    time(info: LogInfo): string;
+    datetime(info: LogInfo): string;
+    level(info: LogInfo): string;
+};
+export default formatters;

package/logging/formatters.js

@@ -0,0 +1,22 @@
+/**
+ * 日志常用数据的格式化函数
+ */
+import { LogLevel } from './index.js';
+const formatters = {
+    time(info) {
+        return info.time.format('HH:mm:ss.SSS');
+    },
+    datetime(info) {
+        return info.time.format('YY-MM-DD HH:mm:ss.SSS');
+    },
+    level(info) {
+        const map = {
+            [LogLevel.Debug]: 'debug',
+            [LogLevel.Info]: 'info',
+            [LogLevel.Warning]: 'warn',
+            [LogLevel.Error]: 'error',
+        };
+        return map[info.level];
+    },
+};
+export default formatters;

package/logging/index.d.ts

@@ -0,0 +1,45 @@
+import { type Dayjs } from 'dayjs';
+export { default as formatters } from './formatters.js';
+export * from './adapt.js';
+export declare enum LogLevel {
+    Debug = 1,
+    Info = 2,
+    Warning = 3,
+    Error = 4
+}
+export declare const logLevelMap: Record<string, LogLevel>;
+export interface LogInfo {
+    logger: string;
+    level: LogLevel;
+    time: Dayjs;
+    args: unknown[];
+}
+export declare class LogHandler {
+    log(info: LogInfo): void;
+}
+export declare class Logger {
+    name: string;
+    base: Logger | null;
+    level: LogLevel;
+    handlers: Set<LogHandler>;
+    constructor(name?: string, base?: Logger | null);
+    static getRealLevel(raw: LogLevel | string): LogLevel;
+    setLevel(level: LogLevel | string): void;
+    addHandler(handler: LogHandler): void;
+    /**
+     * 创建一个以当前 logger 为 base 的 child logger
+     */
+    getChild(name: string): this;
+    log(level: LogLevel | string, args: unknown[]): void;
+    protected logByInfo(info: LogInfo): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}
+/**
+ * 提供一套默认配置好的 logger
+ */
+declare const defaultLogger: Logger;
+export { defaultLogger as logger };
+export declare function getLogger(name: string): Logger;

package/logging/index.js

@@ -0,0 +1,90 @@
+import dayjs from 'dayjs';
+export { default as formatters } from './formatters.js';
+export * from './adapt.js';
+import { initDayJs } from '../init-dayjs.js';
+// 引入 logging 库会自动初始化 dayjs
+initDayJs();
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["Debug"] = 1] = "Debug";
+    LogLevel[LogLevel["Info"] = 2] = "Info";
+    LogLevel[LogLevel["Warning"] = 3] = "Warning";
+    LogLevel[LogLevel["Error"] = 4] = "Error";
+})(LogLevel || (LogLevel = {}));
+export const logLevelMap = {
+    debug: LogLevel.Debug,
+    info: LogLevel.Info,
+    warn: LogLevel.Warning,
+    warning: LogLevel.Warning,
+    err: LogLevel.Error,
+    error: LogLevel.Error,
+};
+export class LogHandler {
+    log(info) { } // eslint-disable-line @typescript-eslint/no-unused-vars
+}
+export class Logger {
+    name;
+    base;
+    level = LogLevel.Info;
+    handlers = new Set();
+    constructor(name = '', base = null) {
+        this.name = name;
+        this.base = base;
+    }
+    static getRealLevel(raw) {
+        if (typeof raw === 'string') {
+            raw = raw.toLowerCase();
+            if (logLevelMap[raw] === undefined)
+                throw new Error('Not supported log level: ' + raw);
+            return logLevelMap[raw];
+        }
+        return raw;
+    }
+    setLevel(level) {
+        this.level = Logger.getRealLevel(level);
+    }
+    addHandler(handler) {
+        this.handlers.add(handler);
+    }
+    /**
+     * 创建一个以当前 logger 为 base 的 child logger
+     */
+    getChild(name) {
+        const fullname = this.name ? `${this.name}/${name}` : name;
+        // 这里加上 `as this` 才能让 TypeScript 判定，对继承了 Logger 的类调用此方法时，返回的是那个类而不是原始的 Logger 类的实例
+        return new this.constructor(fullname, this);
+    }
+    log(level, args) {
+        level = Logger.getRealLevel(level);
+        this.logByInfo({ logger: this.name, level, time: dayjs(), args });
+    }
+    logByInfo(info) {
+        if (this.base)
+            this.base.logByInfo(info);
+        if (this.level > info.level)
+            return;
+        for (const handler of this.handlers) {
+            handler.log(info);
+        }
+    }
+    debug(...args) {
+        this.log(LogLevel.Debug, args);
+    }
+    info(...args) {
+        this.log(LogLevel.Info, args);
+    }
+    warn(...args) {
+        this.log(LogLevel.Warning, args);
+    }
+    error(...args) {
+        this.log(LogLevel.Error, args);
+    }
+}
+/**
+ * 提供一套默认配置好的 logger
+ */
+const defaultLogger = new Logger();
+export { defaultLogger as logger };
+export function getLogger(name) {
+    return defaultLogger.getChild(name);
+}

package/md5.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MD5 算法来自：https://github.com/emn178/js-md5
+ */
+export declare function md5(content: string | ArrayBuffer): string;
+/**
+ * 使用方法：
+ * const md5 = new MD5()
+ * md5.update(xxx)  // 对于大文件，可以拆分开，多次调用 md5.update()
+ * const hash = md5.hex()
+ */
+export declare class MD5 {
+    private readonly buffer8;
+    private readonly blocks;
+    private h0;
+    private h1;
+    private h2;
+    private h3;
+    private start;
+    private bytes;
+    private hBytes;
+    private lastByteIndex;
+    private finalized;
+    private hashed;
+    private first;
+    constructor();
+    update(message: string | number[] | Uint8Array | ArrayBuffer): void;
+    private finalize;
+    private hash;
+    hex(): string;
+}