@anjianshi/utils 2.9.0 → 3.0.0

package/lang/async.js

@@ -1,34 +0,0 @@
-/**
- * 异步行为相关函数
- */
-async function sleep(ms, resolveValue) {
-    return new Promise(resolve => {
-        setTimeout(() => resolve(resolveValue), ms);
-    });
-}
-export { sleep };
-/**
- * 给 Promise 增加时限。
- * - 若 silent 为 false，超时时 reject 一个 TimeoutError
- * - 若 silent 为 true，则超时后，promise 永远不会 resolve 或 reject
- */
-export async function timeout(promise, timeoutMS, silent = false) {
-    return new Promise((resolve, reject) => {
-        let isTimeout = false;
-        setTimeout(() => {
-            isTimeout = true;
-            if (!silent)
-                reject(new TimeoutError('timeout'));
-        }, timeoutMS);
-        promise.then(result => {
-            if (!isTimeout)
-                resolve(result);
-        }, (error) => {
-            if (!isTimeout)
-                reject(error);
-        });
-    });
-}
-export class TimeoutError extends Error {
-    isTimeout = true;
-}

package/lang/color.d.ts

@@ -1,37 +0,0 @@
-/**
- * 计算颜色数值
- */
-/**
- * hex 颜色字符串转换为 rgba 数值
- * 例如 '#22334455' => [34,51,68,0.33]
- *
- * hex 字符串支持以下格式：
- * - 带/不带开头的 #
- * - #RGB
- * - #RGBA
- * - #RRGGBB
- * - #RRGGBBAA
- */
-export declare function hex2rgba(rawHex: string): readonly [number, number, number, number];
-/**
- * 把 rgba 数组转换为 hex 颜色字符串
- * 如果 alpha 部分为 1，会将其省略
- * [34,51,68,0.33] => '#22334455'
- */
-export declare function rgba2hex(rgba: [number, number, number, number]): string;
-/**
- * rgb 转成 hsl 值（以便计算亮度）
- * https://www.rapidtables.com/convert/color/rgb-to-hsl.html
- */
-export declare function rgb2hsl([r, g, b]: [number, number, number]): readonly [number, number, number];
-/**
- * hsl 转成 rgb
- * https://www.rapidtables.com/convert/color/hsl-to-rgb.html
- */
-export declare function hsl2rgb([h, s, l]: [number, number, number]): readonly [number, number, number];
-/**
- * 调整颜色深浅
- * lightness('#111', 0.2)  => lighten(20%)
- * lightness('#111', -0.5)  => darken(50%)
- */
-export declare function lightness(hex: string, ratio: number): string;

package/lang/color.js

@@ -1,111 +0,0 @@
-/**
- * 计算颜色数值
- */
-/**
- * hex 颜色字符串转换为 rgba 数值
- * 例如 '#22334455' => [34,51,68,0.33]
- *
- * hex 字符串支持以下格式：
- * - 带/不带开头的 #
- * - #RGB
- * - #RGBA
- * - #RRGGBB
- * - #RRGGBBAA
- */
-export function hex2rgba(rawHex) {
-    let hex = rawHex;
-    if (hex.startsWith('#'))
-        hex = hex.slice(1); // 去掉开头的 #
-    if (hex.length === 3)
-        hex = `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}FF`;
-    if (hex.length === 4)
-        hex = `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`;
-    if (hex.length === 6)
-        hex = `${hex}FF`;
-    if (hex.length !== 8)
-        throw new Error(`不支持的颜色值：${rawHex}`);
-    hex = hex.toUpperCase(); // 转成全大写
-    const [r, g, b, a255] = [hex.slice(0, 2), hex.slice(2, 4), hex.slice(4, 6), hex.slice(6)].map(part => parseInt(part, 16));
-    const a = Math.round((a255 / 255) * 100) / 100;
-    return [r, g, b, a];
-}
-/**
- * 把 rgba 数组转换为 hex 颜色字符串
- * 如果 alpha 部分为 1，会将其省略
- * [34,51,68,0.33] => '#22334455'
- */
-export function rgba2hex(rgba) {
-    const withAlpha = rgba[3] !== 1;
-    return ('#' +
-        [
-            rgba[0].toString(16),
-            rgba[1].toString(16),
-            rgba[2].toString(16),
-            ...(withAlpha ? [Math.round(rgba[3] * 255).toString(16)] : []),
-        ]
-            .map(v => (v.length === 1 ? `0${v}` : v))
-            .join(''));
-}
-/**
- * rgb 转成 hsl 值（以便计算亮度）
- * https://www.rapidtables.com/convert/color/rgb-to-hsl.html
- */
-export function rgb2hsl([r, g, b]) {
-    const [r1, g1, b1] = [r, g, b].map(v => v / 255);
-    const cMax = Math.max(r1, g1, b1);
-    const cMin = Math.min(r1, g1, b1);
-    const delta = cMax - cMin;
-    let h;
-    if (delta === 0)
-        h = 0;
-    else if (cMax === r1)
-        h = 60 * (((g1 - b1) / delta) % 6);
-    else if (cMax === g1)
-        h = 60 * ((b1 - r1) / delta + 2);
-    else
-        h = 60 * ((r1 - g1) / delta + 4);
-    if (h < 0)
-        h = 360 + h;
-    const roundH = Math.round(h);
-    const l = (cMax + cMin) / 2;
-    const roundL = Math.round(l * 100) / 100;
-    const s = delta === 0 ? 0 : delta / (1 - Math.abs(2 * l - 1));
-    const roundS = Math.round(s * 100) / 100;
-    return [roundH, roundS, roundL];
-}
-/**
- * hsl 转成 rgb
- * https://www.rapidtables.com/convert/color/hsl-to-rgb.html
- */
-export function hsl2rgb([h, s, l]) {
-    const c = (1 - Math.abs(2 * l - 1)) * s;
-    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
-    const m = l - c / 2;
-    const [r1, g1, b1] = (() => {
-        if (h < 60)
-            return [c, x, 0];
-        if (h < 120)
-            return [x, c, 0];
-        if (h < 180)
-            return [0, c, x];
-        if (h < 240)
-            return [0, x, c];
-        if (h < 300)
-            return [x, 0, c];
-        return [c, 0, x];
-    })();
-    const [r, g, b] = [r1 + m, g1 + m, b1 + m].map(v => Math.round(v * 255));
-    return [r, g, b];
-}
-/**
- * 调整颜色深浅
- * lightness('#111', 0.2)  => lighten(20%)
- * lightness('#111', -0.5)  => darken(50%)
- */
-export function lightness(hex, ratio) {
-    const [r, g, b, a] = hex2rgba(hex);
-    const [h, s, l] = rgb2hsl([r, g, b]);
-    const l1 = Math.max(0, Math.min(1, l + ratio));
-    const [r1, g1, b1] = hsl2rgb([h, s, l1]);
-    return rgba2hex([r1, g1, b1, a]);
-}

package/lang/index.d.ts

@@ -1,8 +0,0 @@
-export * from './types.js';
-export * from './may-success.js';
-export * from './string.js';
-export * from './object.js';
-export * from './time.js';
-export * from './async.js';
-export * from './random.js';
-export * from './color.js';

package/lang/index.js

@@ -1,8 +0,0 @@
-export * from './types.js';
-export * from './may-success.js';
-export * from './string.js';
-export * from './object.js';
-export * from './time.js';
-export * from './async.js';
-export * from './random.js';
-export * from './color.js';

package/lang/may-success.d.ts

@@ -1,40 +0,0 @@
-/**
- * MaySuccess：代表一种“可能失败”的操作结果，可以作为函数返回值，也可以作为接口响应值。
- * 它的灵感来自 Scala 的 Option 类型。
- *
- * 原本，在 JavaScript 里一个可能失败的操作有两种表示失败的方式：
- * 1. 返回空值，如 null、0、''
- * 2. 抛出异常
- * 返回空值的方式无法附带失败信息；而抛出异常会导致层层嵌套的 try catch 语句，且其实性能不好。
- *
- * MaySuccess 就是为了解决这两个痛点：
- * 1. 它的 Failed 类型可以携带失败信息。
- * 2. 无需 try catch，只需简单的 result.success 判断
- */
-/** 类型定义 */
-export interface Success<T = void> {
-    success: true;
-    data: T;
-}
-export interface Failed<T = void> {
-    success: false;
-    message: string;
-    code?: string | number;
-    data: T;
-}
-export type MaySuccess<T = void, FT = void> = Success<T> | Failed<FT>;
-/** 生成 Success 数据 */
-declare function success(): Success;
-declare function success<T>(data: T): Success<T>;
-export { success };
-/** 生成 Failed 数据 */
-declare function failed(message: string, code?: string | number): Failed;
-declare function failed<T>(message: string, code: string | number | undefined, data: T): Failed<T>;
-export { failed };
-/**
- * 若传入值为 success，格式化其 data；否则原样返回错误
- * 支持传入会返回 MaySuccess 的 Promise
- */
-declare function formatSuccess<T1, T2, FT = void>(value: MaySuccess<T1, FT>, formatter: (value: T1) => T2): MaySuccess<T2, FT>;
-declare function formatSuccess<T1, T2, FT = void>(value: Promise<MaySuccess<T1, FT>>, formatter: (value: T1) => T2): Promise<MaySuccess<T2, FT>>;
-export { formatSuccess };

package/lang/may-success.js

@@ -1,27 +0,0 @@
-/**
- * MaySuccess：代表一种“可能失败”的操作结果，可以作为函数返回值，也可以作为接口响应值。
- * 它的灵感来自 Scala 的 Option 类型。
- *
- * 原本，在 JavaScript 里一个可能失败的操作有两种表示失败的方式：
- * 1. 返回空值，如 null、0、''
- * 2. 抛出异常
- * 返回空值的方式无法附带失败信息；而抛出异常会导致层层嵌套的 try catch 语句，且其实性能不好。
- *
- * MaySuccess 就是为了解决这两个痛点：
- * 1. 它的 Failed 类型可以携带失败信息。
- * 2. 无需 try catch，只需简单的 result.success 判断
- */
-function success(data) {
-    return { success: true, data };
-}
-export { success };
-function failed(message, code, data) {
-    return { success: false, message, code, data: data };
-}
-export { failed };
-function formatSuccess(value, formatter) {
-    if ('then' in value)
-        return value.then(finalValue => formatSuccess(finalValue, formatter));
-    return value.success ? success(formatter(value.data)) : value;
-}
-export { formatSuccess };

package/lang/object.d.ts

@@ -1,12 +0,0 @@
-/**
- * 对两个对象进行浅比较
- * 代码取自 react-addons-shallow-compare 包
- */
-export declare function shallowEqual(objA: unknown, objB: unknown): boolean;
-/**
- * 获取对象的方法，并将它的 this 锁定在原对象
- *
- * const method = getBoundMethod(object, 'someMethod')
- * method(1,2,3) // 不用担心 this 改变
- */
-export declare function getBoundMethod<T extends object, K extends keyof T>(object: T, key: K): T[K];

package/lang/object.js

@@ -1,41 +0,0 @@
-/**
- * 对两个对象进行浅比较
- * 代码取自 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

@@ -1,13 +0,0 @@
-/**
- * 返回随机数，包含 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

@@ -1,24 +0,0 @@
-/**
- * 返回随机数，包含 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

@@ -1,29 +0,0 @@
-/**
- * 将数字字符串化，并在左侧填充 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

@@ -1,92 +0,0 @@
-/**
- * 字符串处理相关函数
- */
-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

@@ -1,10 +0,0 @@
-/**
- * 时间处理相关函数
- */
-/**
- * 返回指定时间长度的 毫秒数
- */
-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

@@ -1,18 +0,0 @@
-/**
- * 时间处理相关函数
- */
-/**
- * 返回指定时间长度的 毫秒数
- */
-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/lang/types.js

@@ -1,28 +0,0 @@
-/**
- * 对类型系统的辅助、补充
- */
-/**
- * 解决 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

@@ -1,10 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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

@@ -1,10 +0,0 @@
-/**
- * 日志常用数据的格式化函数
- */
-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

@@ -1,22 +0,0 @@
-/**
- * 日志常用数据的格式化函数
- */
-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;