@anjianshi/utils 2.5.0 → 2.7.0

package/env-browser/logging.js

@@ -1,49 +0,0 @@
-/**
- * 针对浏览器环境定制 logging
- */
-import { logger as defaultLogger, LogLevel, LogHandler, formatters, } from '../logging/index.js';
-export * from '../logging/index.js';
-/**
- * 实现向浏览器 console 输出日志
- */
-export class ConsoleHandler extends LogHandler {
-    log(info) {
-        const color = (value = 'black') => `color: ${value};`;
-        const prefix = '%c' + [formatters.time(info), info.logger].map((v) => (v ? `[${v}]` : '')).join('');
-        const prefixColor = info.logger ? color(ConsoleHandler.getColor(info.logger)) : color();
-        const values = [prefix, prefixColor, ...info.args];
-        if (info.level === LogLevel.Debug)
-            console.debug(...values);
-        else if (info.level === LogLevel.Info)
-            console.log(...values);
-        else if (info.level === LogLevel.Warning)
-            console.warn(...values);
-        else
-            console.error(...values);
-    }
-    // 按顺序给各主题分配颜色（取自 http://chriskempson.com/projects/base16/）
-    static colors = [
-        '#dc9656',
-        '#7cafc2',
-        '#ba8baf',
-        '#a16946',
-        '#ab4642',
-        '#86c1b9',
-        '#a1b56c',
-        '#f7ca88',
-    ];
-    static colorMap = new Map();
-    static getColor(name) {
-        if (!ConsoleHandler.colorMap.has(name)) {
-            const nextIndex = ConsoleHandler.colorMap.size % ConsoleHandler.colors.length;
-            ConsoleHandler.colorMap.set(name, ConsoleHandler.colors[nextIndex]);
-        }
-        return ConsoleHandler.colorMap.get(name);
-    }
-}
-/**
- * 预设的初始化行为
- */
-export function initLogger(logger = defaultLogger) {
-    logger.addHandler(new ConsoleHandler());
-}

package/env-browser/manage-vconsole.d.ts

@@ -1,16 +0,0 @@
-import { type default as VConsole } from 'vconsole';
-export declare function registerVConsoleLib(lib: new () => VConsole): void;
-/**
- * 管理 VConsole 实例
- */
-declare global {
-    interface Window {
-        VConsole: VConsole | null;
-    }
-}
-export declare function isVConsoleEnabled(): boolean;
-export declare function detectVConsole(): void;
-export declare function enableVConsole(): void;
-export declare function disableVConsole(): void;
-export declare function runVConsole(): void;
-export declare function destoryVConsole(): void;

package/env-browser/manage-vconsole.js

@@ -1,38 +0,0 @@
-/**
- * 注册 VConsole 代码
- * 此类库自己并不加载 VConsole，需使用者自行通过依赖或者 CDN 加载 VConsole 然后传给此类库
- */
-let VConsoleLib;
-export function registerVConsoleLib(lib) {
-    VConsoleLib = lib;
-}
-window.VConsole = null;
-export function isVConsoleEnabled() {
-    return localStorage.getItem('vconsole') === '1';
-}
-export function detectVConsole() {
-    if (isVConsoleEnabled()) {
-        runVConsole();
-    }
-}
-export function enableVConsole() {
-    localStorage.setItem('vconsole', '1');
-    runVConsole();
-}
-export function disableVConsole() {
-    localStorage.setItem('vconsole', '0');
-    destoryVConsole();
-}
-export function runVConsole() {
-    if (window.VConsole !== null)
-        return;
-    if (VConsoleLib === undefined)
-        return console.warn('尚未传入 VConsole 对象，无法启动');
-    window.VConsole = new VConsoleLib();
-}
-export function destoryVConsole() {
-    if (!window.VConsole)
-        return;
-    window.VConsole.destroy();
-    window.VConsole = null;
-}

package/env-node/crypto-random.d.ts

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

package/env-node/crypto-random.js

@@ -1,28 +0,0 @@
-/**
- * 类似 lang/random.ts，但基于 Node.js 的 crypto 模块，提供密码级的随机数。
- */
-import crypto from 'node:crypto';
-/**
- * 返回随机数，包含 min 和 max
- */
-export function getCryptoRandomInt(min, max) {
-    // 如果传入的 max 小于 min，把它拉到和 min 一样。不然 crypto.randomInt 无法处理
-    const fixedMax = Math.max(min, max);
-    return crypto.randomInt(min, fixedMax + 1);
-}
-/**
- * 返回随机字符串
- */
-export function getCryptoRandomString(length = 6, seed = '0123456789abcdefghijklmnopqrstuvwxyz') {
-    let result = '';
-    while (result.length < length)
-        result += seed[getCryptoRandomInt(0, seed.length - 1)];
-    return result;
-}
-/**
- * 从给定的选择中随机选中一项
- * 如果数组为空，会返回 undefined
- */
-export function cryptoChoiceRandom(choices) {
-    return choices[getCryptoRandomInt(0, choices.length - 1)];
-}

package/env-node/fs.d.ts

@@ -1,19 +0,0 @@
-/**
- * 确认一个路径是否存在且是文件
- */
-export declare function isFileExists(filepath: string): Promise<boolean>;
-/**
- * 确认一个路径是否存在且是文件夹
- */
-export declare function isDirectoryExists(dirpath: string): Promise<boolean>;
-/**
- * 返回当前文件的绝对路径
- * 需要传入当前文件的 ImportMeta 对象（可通过 import.meta 取得）
- */
-export declare function getFilePath(fileUrl: string | ImportMeta): string;
-/**
- * 返回文件所处目录的绝对路径
- */
-export declare function getDirectoryPath(fileUrl: string | ImportMeta): string;
-/** 确保目录存在，如果不存在就创建（会递归创建上级目录） */
-export declare function mkdirp(dirpath: string, mode?: number | string): Promise<void>;

package/env-node/fs.js

@@ -1,48 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-/**
- * 确认一个路径是否存在且是文件
- */
-export async function isFileExists(filepath) {
-    try {
-        const res = await fs.promises.stat(filepath);
-        return res.isFile();
-    }
-    catch (e) {
-        return false;
-    }
-}
-/**
- * 确认一个路径是否存在且是文件夹
- */
-export async function isDirectoryExists(dirpath) {
-    try {
-        const res = await fs.promises.stat(dirpath);
-        return res.isDirectory();
-    }
-    catch (e) {
-        return false;
-    }
-}
-/**
- * 返回当前文件的绝对路径
- * 需要传入当前文件的 ImportMeta 对象（可通过 import.meta 取得）
- */
-export function getFilePath(fileUrl) {
-    if (typeof fileUrl !== 'string')
-        fileUrl = fileUrl.url;
-    return fileURLToPath(new URL(fileUrl));
-}
-/**
- * 返回文件所处目录的绝对路径
- */
-export function getDirectoryPath(fileUrl) {
-    return path.dirname(getFilePath(fileUrl));
-}
-/** 确保目录存在，如果不存在就创建（会递归创建上级目录） */
-export async function mkdirp(dirpath, mode) {
-    if (!(await isDirectoryExists(dirpath))) {
-        await fs.promises.mkdir(dirpath, { recursive: true, mode });
-    }
-}

package/env-node/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Node.js 环境下的工具函数
- */
-export * from './fs.js';
-export * from './crypto-random.js';

package/env-node/index.js

@@ -1,5 +0,0 @@
-/**
- * Node.js 环境下的工具函数
- */
-export * from './fs.js';
-export * from './crypto-random.js';

package/env-node/logging/handlers.d.ts

@@ -1,58 +0,0 @@
-import { type LogInfo, LogHandler } from '../../logging/index.js';
-/**
- * 向 console 输出日志
- */
-export declare class ConsoleHandler extends LogHandler {
-    log(info: LogInfo): void;
-    static readonly consoleMethods: {
-        1: {
-            (...data: any[]): void;
-            (message?: any, ...optionalParams: any[]): void;
-        };
-        2: {
-            (...data: any[]): void;
-            (message?: any, ...optionalParams: any[]): void;
-        };
-        3: {
-            (...data: any[]): void;
-            (message?: any, ...optionalParams: any[]): void;
-        };
-        4: {
-            (...data: any[]): void;
-            (message?: any, ...optionalParams: any[]): void;
-        };
-    };
-    static readonly levelColors: {
-        1: import("chalk").ChalkInstance;
-        2: import("chalk").ChalkInstance;
-        3: import("chalk").ChalkInstance;
-        4: import("chalk").ChalkInstance;
-    };
-    private static readonly loggerColors;
-    private static readonly loggerColorMap;
-    static getLoggerColor(logger: string): "green" | "yellow" | "blue" | "cyan" | "magenta" | "greenBright" | "yellowBright" | "blueBright" | "cyanBright" | "magentaBright";
-}
-/**
- * 写入文件日志
- */
-export interface FileHandlerOptions {
-    dir: string;
-    filePrefix: string;
-    maxLength: number;
-    flushLength: number;
-    flushInterval: number;
-}
-export declare class FileHandler extends LogHandler {
-    readonly options: FileHandlerOptions;
-    constructor(options?: Partial<FileHandlerOptions>);
-    log(info: LogInfo): void;
-    protected stringifyDataItem(item: unknown): string;
-    private buffer;
-    private bufferSize;
-    private flushTimeoutId;
-    protected pushBuffer(...strings: string[]): void;
-    protected flush(sync?: boolean): void;
-    get filepath(): string;
-    protected initLogDir(): void;
-    protected write(content: string, sync?: boolean): void;
-}

package/env-node/logging/handlers.js

@@ -1,154 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import util from 'node:util';
-import chalk from 'chalk';
-import dayjs from 'dayjs';
-import { LogLevel, LogHandler, formatters } from '../../logging/index.js';
-/**
- * 向 console 输出日志
- */
-export class ConsoleHandler extends LogHandler {
-    log(info) {
-        const { logger, level, args } = info;
-        const method = ConsoleHandler.consoleMethods[level];
-        const levelColor = ConsoleHandler.levelColors[level];
-        const levelName = formatters.level(info);
-        const loggerColor = chalk[ConsoleHandler.getLoggerColor(logger)];
-        const prefix = [
-            chalk.white(`[${formatters.time(info)}]`),
-            levelColor(`[${levelName}]`),
-            ...(logger ? [loggerColor(`[${logger}]`)] : []),
-        ].join('');
-        method(prefix, ...args);
-    }
-    static consoleMethods = {
-        [LogLevel.Debug]: console.debug.bind(console),
-        [LogLevel.Info]: console.info.bind(console),
-        [LogLevel.Warning]: console.warn.bind(console),
-        [LogLevel.Error]: console.error.bind(console),
-    };
-    static levelColors = {
-        [LogLevel.Debug]: chalk.whiteBright,
-        [LogLevel.Info]: chalk.white,
-        [LogLevel.Warning]: chalk.yellowBright,
-        [LogLevel.Error]: chalk.redBright,
-    };
-    // 可供 logger 选择的颜色
-    static loggerColors = [
-        'green',
-        'yellow',
-        'blue',
-        'magenta',
-        'cyan',
-        'greenBright',
-        'yellowBright',
-        'blueBright',
-        'magentaBright',
-        'cyanBright',
-    ];
-    static loggerColorMap = new Map();
-    static getLoggerColor(logger) {
-        if (!ConsoleHandler.loggerColorMap.has(logger)) {
-            const color = ConsoleHandler.loggerColors[ConsoleHandler.loggerColorMap.size % ConsoleHandler.loggerColors.length];
-            ConsoleHandler.loggerColorMap.set(logger, color);
-        }
-        return ConsoleHandler.loggerColorMap.get(logger);
-    }
-}
-export class FileHandler extends LogHandler {
-    options;
-    constructor(options) {
-        super();
-        const dirname = path.dirname(fileURLToPath(new URL(import.meta.url)));
-        this.options = {
-            dir: path.resolve(dirname, 'logs'),
-            filePrefix: '',
-            maxLength: 10000,
-            flushLength: 100000,
-            flushInterval: 1000,
-            ...(options ?? {}),
-        };
-        this.initLogDir();
-        // 进程退出前把尚未写入文件的日志强制写入
-        // 这里必须用同步的方式来写，不然会写入不进去（可能是因为异步的话是放到下一个事件循环，但进程在这个事件循环内就退出了）
-        process.on('exit', () => this.flush(true));
-    }
-    // Format log content
-    log(info) {
-        const { logger, args } = info;
-        const prefix = [
-            `[${formatters.datetime(info)}]`,
-            `[${formatters.level(info)}]`,
-            logger ? `[${logger}]` : '',
-        ].join('') + ' ';
-        const itemStrings = [];
-        let totalLength = prefix.length;
-        for (const item of args) {
-            const itemString = this.stringifyDataItem(item);
-            // 截断过长的日志内容 Truncate overly long log messages
-            if (totalLength + itemString.length < this.options.maxLength) {
-                itemStrings.push((totalLength === prefix.length ? '' : ' ') + itemString);
-                totalLength += itemString.length;
-            }
-            else {
-                itemStrings.push(itemString.slice(0, this.options.maxLength - totalLength) + ' [too long, sliced]');
-                break;
-            }
-        }
-        this.pushBuffer(prefix, ...itemStrings, '\n');
-    }
-    stringifyDataItem(item) {
-        // 去掉颜色控制字符
-        if (typeof item === 'string')
-            item = item.replace(/\x1b\[\d+m/g, '');
-        // 利用 util.format() 获得和 console.log() 相同的输出（因为 console.log() 底层也是用的 util.format()）
-        return util.format(item);
-    }
-    // Handle buffer & flush
-    buffer = [];
-    bufferSize = 0;
-    flushTimeoutId = null;
-    pushBuffer(...strings) {
-        this.buffer.push(...strings);
-        this.bufferSize = strings.reduce((sum, v) => sum + v.length, this.bufferSize);
-        if (this.options.flushInterval === 0 || this.bufferSize >= this.options.flushLength) {
-            this.flush();
-        }
-        else if (!this.flushTimeoutId) {
-            this.flushTimeoutId = setTimeout(() => this.flush(), this.options.flushInterval);
-        }
-    }
-    flush(sync) {
-        if (this.flushTimeoutId) {
-            clearTimeout(this.flushTimeoutId);
-            this.flushTimeoutId = null;
-        }
-        if (this.buffer.length) {
-            const content = this.buffer.join('');
-            this.buffer = [];
-            this.bufferSize = 0;
-            this.write(content, sync);
-        }
-    }
-    // 文件系统交互 File system interaction
-    get filepath() {
-        const { dir, filePrefix } = this.options;
-        return path.join(dir, `${filePrefix ? `${filePrefix}-` : ''}${dayjs().format('YYYY-MM-DD')}.log`);
-    }
-    initLogDir() {
-        if (!fs.existsSync(this.options.dir))
-            fs.mkdirSync(this.options.dir);
-    }
-    write(content, sync = false) {
-        if (sync) {
-            fs.appendFileSync(this.filepath, content);
-        }
-        else {
-            fs.appendFile(this.filepath, content, error => {
-                if (error)
-                    console.error('[logger] write failed: ', error);
-            });
-        }
-    }
-}

package/env-node/logging/index.d.ts

@@ -1,11 +0,0 @@
-/**
- * 针对 Node.js 环境定制 logging
- * 注意：使用此模块需要 chalk 依赖
- */
-import { type Logger } from '../../logging/index.js';
-export * from './handlers.js';
-export * from '../../logging/index.js';
-/**
- * 预设的初始化行为
- */
-export declare function initLogger(logger?: Logger): void;

package/env-node/logging/index.js

@@ -1,14 +0,0 @@
-/**
- * 针对 Node.js 环境定制 logging
- * 注意：使用此模块需要 chalk 依赖
- */
-import { logger as defaultLogger } from '../../logging/index.js';
-import { ConsoleHandler } from './handlers.js';
-export * from './handlers.js';
-export * from '../../logging/index.js';
-/**
- * 预设的初始化行为
- */
-export function initLogger(logger = defaultLogger) {
-    logger.addHandler(new ConsoleHandler());
-}

package/env-react/emotion.d.ts

@@ -1,20 +0,0 @@
-/**
- * 通过 React Hook 把 emotion css 转换成 className
- * （不再需要 <ClassName>）
- *
- * 使用前提：
- * 1. 只支持浏览器渲染
- * 2. 用 EmotionCacheProvider 包裹 App 根元素
- *
- * 来自：
- * https://github.com/emotion-js/emotion/issues/1853#issuecomment-623349622
- */
-import { type EmotionCache } from '@emotion/react';
-import { type CSSInterpolation } from '@emotion/serialize';
-export declare const useEmotionCache: () => EmotionCache | undefined;
-export declare const EmotionCacheProvider: import("react").FC<{
-    children: React.ReactNode;
-} & import("react").RefAttributes<any>> | import("react").ForwardRefExoticComponent<{
-    children: React.ReactNode;
-} & import("react").RefAttributes<any>>;
-export declare function useEmotionClassName(): (...args: CSSInterpolation[]) => string;

package/env-react/emotion.jsx

@@ -1,34 +0,0 @@
-/**
- * 通过 React Hook 把 emotion css 转换成 className
- * （不再需要 <ClassName>）
- *
- * 使用前提：
- * 1. 只支持浏览器渲染
- * 2. 用 EmotionCacheProvider 包裹 App 根元素
- *
- * 来自：
- * https://github.com/emotion-js/emotion/issues/1853#issuecomment-623349622
- */
-import { withEmotionCache } from '@emotion/react';
-import { serializeStyles } from '@emotion/serialize';
-import { insertStyles } from '@emotion/utils';
-import { createContext, useContext, useCallback } from 'react';
-const CacheContext = createContext(undefined);
-export const useEmotionCache = () => useContext(CacheContext);
-export const EmotionCacheProvider = withEmotionCache(({ children }, cache) => {
-    return <CacheContext.Provider value={cache}>{children}</CacheContext.Provider>;
-});
-export function useEmotionClassName() {
-    const cache = useEmotionCache();
-    return useCallback((...args) => {
-        if (!cache) {
-            if (process.env.NODE_ENV === 'production') {
-                return 'emotion-cache-missing';
-            }
-            throw new Error('No emotion cache found!');
-        }
-        const serialized = serializeStyles(args, cache.registered);
-        insertStyles(cache, serialized, false);
-        return cache.key + '-' + serialized.name;
-    }, [cache]);
-}

package/env-service/controllers.d.ts

@@ -1,30 +0,0 @@
-/**
- * 把业务功能整理成各个 Controller，
- * 并整合成一个 controllers 对象方便外部引用和 Controller 之间互相引用。
- *
- * 支持自定义 Controller 类，例如把 context 中的内容定义成属性。
- */
-export type AnyObject = Record<string, unknown>;
-export type AnyController<Context> = Controller<Context, any>;
-type AnyControllerClass<Context> = typeof Controller<Context, any>;
-export type ControllersFrom<Context, T extends AnyObject> = {
-    [K in keyof T]: T[K] extends AnyControllerClass<Context> ? InstanceType<T[K]> : never;
-};
-/**
- * Controller 基类
- */
-export declare class Controller<Context, AllControllers extends Record<string, AnyController<Context>>> {
-    /** 调用其他 controllers */
-    protected readonly controllers: AllControllers;
-    protected readonly context: Context;
-    protected readonly name: string;
-    constructor(
-    /** 调用其他 controllers */
-    controllers: AllControllers, context: Context, name?: string);
-}
-/**
- * 传入 Controller 类列表，返回 controller 实例集合。
- * 为优化性能，每个 controller 只有在被使用到时才会实例化。
- */
-export declare function initializeControllers<Context, T extends AnyObject>(controllerClasses: T, context: Context): ControllersFrom<Context, T>;
-export {};

package/env-service/controllers.js

@@ -1,41 +0,0 @@
-/**
- * 把业务功能整理成各个 Controller，
- * 并整合成一个 controllers 对象方便外部引用和 Controller 之间互相引用。
- *
- * 支持自定义 Controller 类，例如把 context 中的内容定义成属性。
- */
-/**
- * Controller 基类
- */
-export class Controller {
-    controllers;
-    context;
-    name;
-    constructor(
-    /** 调用其他 controllers */
-    controllers, context, name = this.constructor.name) {
-        this.controllers = controllers;
-        this.context = context;
-        this.name = name;
-    }
-}
-/**
- * 传入 Controller 类列表，返回 controller 实例集合。
- * 为优化性能，每个 controller 只有在被使用到时才会实例化。
- */
-export function initializeControllers(controllerClasses, context) {
-    const proxy = new Proxy({}, {
-        get(controllers, prop) {
-            if (typeof prop !== 'string')
-                return;
-            if (prop in controllers)
-                return controllers[prop];
-            if (prop in controllerClasses) {
-                const Class = controllerClasses[prop];
-                controllers[prop] = new Class(proxy, context, prop);
-                return controllers[prop];
-            }
-        },
-    });
-    return proxy;
-}

package/env-service/env-reader.d.ts

@@ -1,55 +0,0 @@
-import * as dotenv from 'dotenv';
-type EnvValue = string | number | boolean | unknown[] | Record<string, unknown>;
-type TypeDef = 'string' | 'number' | 'boolean' | unknown[] | Record<string, unknown>;
-type TypeFrom<D extends TypeDef> = D extends 'string' ? string : D extends 'number' ? number : D extends 'boolean' ? boolean : D;
-type ResultFrom<Defs extends Record<string, TypeDef>> = {
-    [K in keyof Defs]: TypeFrom<Defs[K]>;
-};
-/**
- * 读取 .env 文件，并获取格式化后的数据
- * 注意：依赖 dotenv 包
- */
-export declare class EnvReader {
-    protected loadedEnvs: Record<string, string>;
-    constructor(options?: dotenv.DotenvConfigOptions);
-    protected toNumber(raw: string): number | undefined;
-    protected toBoolean(raw: string): boolean | undefined;
-    getRaw(key: string): string | undefined;
-    /**
-     * 获取指定 env 的值，并转换成与 defaults 匹配的类型。
-     * 若值不存在，返回 defaults。
-     */
-    get(key: string, defaults: string): string;
-    get(key: string, defaults: number): number;
-    get(key: string, defaults: boolean): boolean;
-    get<T extends unknown[] | Record<string, unknown>>(key: string, defaults: T): T;
-    /**
-     * 获取指定 env 的值，并转换成指定类型，无需提供默认值。
-     * 值不存在或转换失败时，返回 undefined。
-     */
-    getByType(key: string, type?: 'string'): string | undefined;
-    getByType(key: string, type: 'number'): number | undefined;
-    getByType(key: string, type: 'boolean'): boolean | undefined;
-    getByType<T extends unknown[] | Record<string, unknown>>(key: string, type: 'json'): T | undefined;
-    /**
-     * 同 envReader.get()，只不过是通过对象指定各 env 的默认值来批量获取
-     * envReader.batchGet({ port: 8000, debug: false, mobiles: ['123', '456'] }
-     */
-    batchGet<Defs extends Record<string, EnvValue>>(definitions: Defs): { [K in keyof Defs]: Defs[K] extends string ? string : Defs[K] extends number ? number : Defs[K] extends boolean ? boolean : Defs[K]; };
-    /**
-     * 同 envReader.getByType()，只不过是通过对象指定各 env 的类型来批量获取。
-     *
-     * - required=false（默认）时，不存在或值为 undefined 的 env 不会出现在返回对象里，以保证 { ...defaults, ...envReader.batchGetByType(...) } 的用法能正常保留默认值。
-     * - required=true 时要求所有 env 都必须有值，否则会抛出异常
-     *
-     * envReader.batchGetByType({
-     *   port: 'number',
-     *   debug: 'boolean',
-     *   mobiles: [] as string[],  // 用此格式定义内容是数组的 JSON 值
-     *   obj: {} as { a: number, b: string } // 用此格式定义内容是对象的 JSON 值
-     * })
-     */
-    batchGetByType<Defs extends Record<string, TypeDef>>(definitions: Defs, required?: false): Partial<ResultFrom<Defs>>;
-    batchGetByType<Defs extends Record<string, TypeDef>>(definitions: Defs, required: true): ResultFrom<Defs>;
-}
-export {};