@anjianshi/utils 2.5.0 → 2.6.0

package/env-service/redis-cache.js

@@ -1,116 +0,0 @@
-import { logger as rootLogger } from '../logging/index.js';
-export function initRedisLogging(redis, logger) {
-    logger ??= rootLogger.getChild('redis');
-    redis.on('connect', () => logger.info('connecting'));
-    redis.on('ready', () => logger.info('connected'));
-    redis.on('end', () => logger.info('connection closed'));
-    redis.on('reconnecting', () => logger.info('reconnecting'));
-    redis.on('error', error => logger.error(error));
-}
-/**
- * 维护缓存数据
- * 1. 每个 Cache 实例只维护一个主题的数据，且需明确定义数据类型，这样设计可明确对每一项缓存的使用、避免混乱。
- * 2. 值在存储时会 JSON 化，读取时再进行 JSON 解析（支持 JSON 化 Date 对象）。
- */
-export class Cache {
-    redis;
-    topic;
-    options;
-    constructor(redis, topic, options) {
-        this.redis = redis;
-        this.topic = topic;
-        this.options = {
-            logger: rootLogger.getChild('cache'),
-            expires: 600,
-            refreshOnRead: true,
-            oneTime: false,
-            ...(options ?? {}),
-        };
-    }
-    get logger() {
-        return this.options.logger;
-    }
-    // 经过定制的 JSON 序列化和解析方法
-    jsonStringify(value) {
-        // 参考：https://stackoverflow.com/a/54037861/2815178
-        function replacer(key, value) {
-            // value 是经过预处理过的值，对于 Date 对象，此时已经是 string，需要通过 this[key] 才能拿到 Date 值。
-            const rawValue = this[key];
-            if (rawValue instanceof Date)
-                return { __json_type: 'date', value: rawValue.toISOString() };
-            return value;
-        }
-        return JSON.stringify(value, replacer);
-    }
-    jsonParse(redisValue) {
-        function reviver(key, value) {
-            if (typeof value === 'object' && value !== null) {
-                const obj = value;
-                if (obj.__json_type === 'date')
-                    return new Date(obj.value);
-            }
-            return value;
-        }
-        return JSON.parse(redisValue, reviver);
-    }
-    getRedisKey(identity) {
-        return `${this.topic}${identity ? ':' + identity : ''}`;
-    }
-    async get(identity = '', defaults) {
-        const redisKey = this.getRedisKey(identity);
-        const redisValue = await this.redis.get(redisKey);
-        this.logger.debug('get', redisKey, redisValue);
-        if (redisValue === null)
-            return defaults;
-        if (this.options.refreshOnRead)
-            void this.refresh(identity);
-        try {
-            const value = this.jsonParse(redisValue);
-            if (this.options.oneTime)
-                await this.delete(identity);
-            return value;
-        }
-        catch (error) {
-            this.logger.error(`解析 cache 数据失败，key=${redisKey}，value=${redisValue}`, error);
-            void this.delete(identity);
-            return defaults;
-        }
-    }
-    async set(identity, value) {
-        if (value === undefined) {
-            value = identity;
-            identity = '';
-        }
-        else {
-            identity = identity;
-        }
-        const redisKey = this.getRedisKey(identity);
-        let redisValue;
-        try {
-            redisValue = this.jsonStringify(value);
-        }
-        catch (error) {
-            this.logger.error(`格式化 cache 数据失败，key=${redisKey}`, value, error);
-            throw error;
-        }
-        this.logger.debug('set', redisKey, redisValue);
-        await this.redis.set(redisKey, redisValue, { EX: this.options.expires });
-    }
-    /** 移除一项内容 */
-    async delete(identity = '') {
-        const identities = Array.isArray(identity) ? identity : [identity];
-        this.logger.debug('delete', identities);
-        return this.redis.del(identities.map(identity => this.getRedisKey(identity)));
-    }
-    /** 刷新一项内容的过期时间 */
-    async refresh(identity = '') {
-        if (this.options.expires >= 0)
-            return this.redis.expire(this.getRedisKey(identity), this.options.expires);
-        else
-            return false;
-    }
-    /** 确认一项内容是否存在  */
-    async exists(identity = '') {
-        return (await this.redis.exists(this.getRedisKey(identity))) === 1;
-    }
-}

package/env-service/tasks.d.ts

@@ -1,12 +0,0 @@
-import { type Logger } from '../logging/index.js';
-/** 返回 false 可结束任务 */
-export type TaskExecutor<Context> = (context: Context, logger: Logger) => Promise<void> | Promise<undefined | boolean>;
-/**
- * 执行定期任务
- */
-export declare abstract class TaskManager<Context> {
-    protected baseLogger: Logger;
-    constructor(baseLogger?: Logger);
-    abstract getContext(taskName: string): Context;
-    run(name: string, interval: number, executor: TaskExecutor<Context>): Promise<void>;
-}

package/env-service/tasks.js

@@ -1,37 +0,0 @@
-import { sleep } from '../lang/async.js';
-import { logger as rootLogger } from '../logging/index.js';
-/**
- * 执行定期任务
- */
-export class TaskManager {
-    baseLogger;
-    constructor(baseLogger = rootLogger.getChild('task')) {
-        this.baseLogger = baseLogger;
-    }
-    async run(name, interval, executor) {
-        await sleep(1000);
-        const logger = this.baseLogger.getChild(name);
-        let nextId = 1;
-        while (true) {
-            const id = nextId++;
-            if (id >= Number.MAX_SAFE_INTEGER)
-                nextId = 1;
-            const start = Date.now();
-            logger.info(`#${id} 任务开始`);
-            try {
-                const context = this.getContext(name);
-                const result = await executor(context, logger);
-                const cost = (Date.now() - start) / 1000;
-                logger.info(`#${id} 任务完成，耗时 ${cost}s`);
-                if (result === false) {
-                    logger.info('任务结束');
-                    break;
-                }
-            }
-            catch (err) {
-                logger.error(`#${id} 任务失败`, err);
-            }
-            await sleep(interval);
-        }
-    }
-}

package/index.d.ts

@@ -1,3 +0,0 @@
-export * from './lang/index.js';
-export * from './url.js';
-export * from './logging/index.js';

package/index.js

@@ -1,3 +0,0 @@
-export * from './lang/index.js';
-export * from './url.js';
-export * from './logging/index.js';

package/init-dayjs.d.ts

@@ -1,2 +0,0 @@
-import 'dayjs/locale/zh-cn.js';
-export declare function initDayJs(): void;

package/init-dayjs.js

@@ -1,7 +0,0 @@
-import dayjs from 'dayjs';
-import objectSupport from 'dayjs/plugin/objectSupport.js';
-import 'dayjs/locale/zh-cn.js';
-export function initDayJs() {
-    dayjs.extend(objectSupport);
-    dayjs.locale('zh-cn');
-}

package/lang/async.d.ts

@@ -1,19 +0,0 @@
-/**
- * 异步行为相关函数
- */
-/**
- * 返回一个指定毫秒后 resolve 的 Promise
- * 若指定了 resolveValue，则 Promise 最终会解析出此值
- */
-declare function sleep(ms: number): Promise<void>;
-declare function sleep<T>(ms: number, resolveValue: T): Promise<T>;
-export { sleep };
-/**
- * 给 Promise 增加时限。
- * - 若 silent 为 false，超时时 reject 一个 TimeoutError
- * - 若 silent 为 true，则超时后，promise 永远不会 resolve 或 reject
- */
-export declare function timeout<T>(promise: Promise<T>, timeoutMS: number, silent?: boolean): Promise<T>;
-export declare class TimeoutError extends Error {
-    isTimeout: boolean;
-}

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/index.d.ts

@@ -1,7 +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';

package/lang/index.js

@@ -1,7 +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';

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,5 +0,0 @@
-/**
- * 对两个对象进行浅比较
- * 代码取自 react-addons-shallow-compare 包
- */
-export declare function shallowEqual(objA: unknown, objB: unknown): boolean;

package/lang/object.js

@@ -1,31 +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;
-}

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;