@anjianshi/utils 3.0.0 → 3.0.2

package/env-browser/device.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 自动计算最合适的 rem 大小，应用到页面样式上。
+ *
+ * rem 的意义是对于大屏幕，适当地同步放大界面元素，以提供更饱满的显示效果。
+ * 不过也不是所有地方都原封不动地大就好了，所以还要配合 media query 来实现最佳效果。
+ */
+export declare function autoRem(): void;
+/**
+ * 当前设备是否是全面屏
+ * 页面刚加载时可能取不到 offsetHeight，因此通过一个函数而不是常量来提供此值
+ */
+export declare function isFullScreen(): boolean;
+/**
+ * 当前是否是 iOS 设备
+ */
+export declare const isIOS: boolean;
+/**
+ * 当前是否是移动设备
+ */
+export declare const isMobile: boolean;
+/**
+ * 当前是否是微信内部浏览器
+ */
+export declare const isWechat: boolean;

package/env-browser/device.js

@@ -0,0 +1,50 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
+/**
+ * 自动计算最合适的 rem 大小，应用到页面样式上。
+ *
+ * rem 的意义是对于大屏幕，适当地同步放大界面元素，以提供更饱满的显示效果。
+ * 不过也不是所有地方都原封不动地大就好了，所以还要配合 media query 来实现最佳效果。
+ */
+export function autoRem() {
+    const resizeEvt = 'orientationchange' in window ? 'orientationchange' : 'resize';
+    /**
+     * 计算规则：
+     * - 微信标准的 375px 宽度下，1rem 为 50px（这个比例的来由是这样的：移动端通常像素比 >= 2，这个 375px 的实际渲染像素是 750px，也就是实际渲染 750px 的情况下，1rem 为 100px）。
+     * - 在平板等特大屏幕下，限制 rem 的最大值为 75px，再大就夸张了。
+     * - 竖屏时取宽度来适配 rem，横屏时取高度来适配，以保证屏幕朝向不同时，界面元素的放大比例是一致的（这应该更符合人的认知：对于一个同样大小的屏幕，无论什么朝向，上面的文字应该是一样大的）。
+     *   注意：此计算方式仅适合“不能任意调整浏览器大小的”移动设备，对于浏览器窗口可能任意尺寸、比例的桌面端，还是应该始终按照宽度来适配。
+     *
+     * 从 px 到 rem 的换算：
+     * 原 px 单位的值换算成 rem，只要除以 50 即可。例如 12px 变成 0.24rem。
+     */
+    function updateRem() {
+        const { clientWidth, clientHeight } = document.documentElement;
+        const refSize = Math.min(clientWidth, clientHeight);
+        const rem = Math.min((refSize / 750) * 100, 75);
+        document.documentElement.style.fontSize = `${rem}px`;
+    }
+    window.addEventListener(resizeEvt, updateRem, false);
+    document.addEventListener('DOMContentLoaded', updateRem, false);
+}
+/**
+ * 当前设备是否是全面屏
+ * 页面刚加载时可能取不到 offsetHeight，因此通过一个函数而不是常量来提供此值
+ */
+export function isFullScreen() {
+    const rate = document.documentElement.offsetHeight / document.documentElement.offsetWidth;
+    const limit = window.screen.height === window.screen.availHeight ? 1.8 : 1.65; // 临界判断值
+    return rate > limit;
+}
+/**
+ * 当前是否是 iOS 设备
+ */
+export const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
+/**
+ * 当前是否是移动设备
+ */
+export const isMobile = /(android|bb\d+|meego).+mobile|avantgo|bada\/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|mobile.+firefox|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)\/|plucker|pocket|psp|series(4|6)0|symbian|treo|up\.(browser|link)|vodafone|wap|windows ce|xda|xiino/i.test(navigator.userAgent || navigator.vendor) ||
+    /1207|6310|6590|3gso|4thp|50[1-6]i|770s|802s|a wa|abac|ac(er|oo|s-)|ai(ko|rn)|al(av|ca|co)|amoi|an(ex|ny|yw)|aptu|ar(ch|go)|as(te|us)|attw|au(di|-m|r |s )|avan|be(ck|ll|nq)|bi(lb|rd)|bl(ac|az)|br(e|v)w|bumb|bw-(n|u)|c55\/|capi|ccwa|cdm-|cell|chtm|cldc|cmd-|co(mp|nd)|craw|da(it|ll|ng)|dbte|dc-s|devi|dica|dmob|do(c|p)o|ds(12|-d)|el(49|ai)|em(l2|ul)|er(ic|k0)|esl8|ez([4-7]0|os|wa|ze)|fetc|fly(-|_)|g1 u|g560|gene|gf-5|g-mo|go(\.w|od)|gr(ad|un)|haie|hcit|hd-(m|p|t)|hei-|hi(pt|ta)|hp( i|ip)|hs-c|ht(c(-| |_|a|g|p|s|t)|tp)|hu(aw|tc)|i-(20|go|ma)|i230|iac( |-|\/)|ibro|idea|ig01|ikom|im1k|inno|ipaq|iris|ja(t|v)a|jbro|jemu|jigs|kddi|keji|kgt( |\/)|klon|kpt |kwc-|kyo(c|k)|le(no|xi)|lg( g|\/(k|l|u)|50|54|-[a-w])|libw|lynx|m1-w|m3ga|m50\/|ma(te|ui|xo)|mc(01|21|ca)|m-cr|me(rc|ri)|mi(o8|oa|ts)|mmef|mo(01|02|bi|de|do|t(-| |o|v)|zz)|mt(50|p1|v )|mwbp|mywa|n10[0-2]|n20[2-3]|n30(0|2)|n50(0|2|5)|n7(0(0|1)|10)|ne((c|m)-|on|tf|wf|wg|wt)|nok(6|i)|nzph|o2im|op(ti|wv)|oran|owg1|p800|pan(a|d|t)|pdxg|pg(13|-([1-8]|c))|phil|pire|pl(ay|uc)|pn-2|po(ck|rt|se)|prox|psio|pt-g|qa-a|qc(07|12|21|32|60|-[2-7]|i-)|qtek|r380|r600|raks|rim9|ro(ve|zo)|s55\/|sa(ge|ma|mm|ms|ny|va)|sc(01|h-|oo|p-)|sdk\/|se(c(-|0|1)|47|mc|nd|ri)|sgh-|shar|sie(-|m)|sk-0|sl(45|id)|sm(al|ar|b3|it|t5)|so(ft|ny)|sp(01|h-|v-|v )|sy(01|mb)|t2(18|50)|t6(00|10|18)|ta(gt|lk)|tcl-|tdg-|tel(i|m)|tim-|t-mo|to(pl|sh)|ts(70|m-|m3|m5)|tx-9|up(\.b|g1|si)|utst|v400|v750|veri|vi(rg|te)|vk(40|5[0-3]|-v)|vm40|voda|vulc|vx(52|53|60|61|70|80|81|83|85|98)|w3c(-| )|webc|whit|wi(g |nc|nw)|wmlb|wonu|x700|yas-|your|zeto|zte-/i.test((navigator.userAgent || navigator.vendor).substr(0, 4));
+/**
+ * 当前是否是微信内部浏览器
+ */
+export const isWechat = /micromessenger/i.test(navigator.userAgent);

package/env-browser/global.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 通过此模块注册全局变量以便于调试
+ * 变量会注册到 window.app = {} 下
+ */
+declare global {
+    interface Window {
+        app: Record<string, unknown>;
+    }
+}
+export default function registerGlobal(key: string, content: unknown): void;

package/env-browser/global.js

@@ -0,0 +1,15 @@
+/**
+ * 通过此模块注册全局变量以便于调试
+ * 变量会注册到 window.app = {} 下
+ */
+// web-worker 环境下不存在 window 变量，无法执行注册
+let hasWindow = false;
+try {
+    window.app = {};
+    hasWindow = true;
+}
+catch (e) { } // eslint-disable-line no-empty
+export default function registerGlobal(key, content) {
+    if (hasWindow)
+        window.app[key] = content;
+}

package/env-browser/load-script.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 加载脚本文件
+ * 返回 Promise，成功则 resolve，失败 reject
+ */
+export default function loadScript(url: string): Promise<void>;

package/env-browser/load-script.js

@@ -0,0 +1,13 @@
+/**
+ * 加载脚本文件
+ * 返回 Promise，成功则 resolve，失败 reject
+ */
+export default async function loadScript(url) {
+    return new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = url;
+        script.onload = () => resolve();
+        script.onerror = err => reject(err); // eslint-disable-line @typescript-eslint/prefer-promise-reject-errors
+        window.document.head.appendChild(script);
+    });
+}

package/env-browser/logging.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 针对浏览器环境定制 logging
+ */
+import { type Logger, type LogInfo, LogHandler } from '../logging/index.js';
+export * from '../logging/index.js';
+/**
+ * 实现向浏览器 console 输出日志
+ */
+export declare class ConsoleHandler extends LogHandler {
+    log(info: LogInfo): void;
+    private static readonly colors;
+    private static readonly colorMap;
+    static getColor(name: string): string;
+}
+/**
+ * 预设的初始化行为
+ */
+export declare function initLogger(logger?: Logger): void;

package/env-browser/logging.js

@@ -0,0 +1,49 @@
+/**
+ * 针对浏览器环境定制 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

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

@@ -0,0 +1,38 @@
+/**
+ * 注册 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

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

@@ -0,0 +1,28 @@
+/**
+ * 类似 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

@@ -0,0 +1,19 @@
+/**
+ * 确认一个路径是否存在且是文件
+ */
+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

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

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

package/env-node/index.js

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

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * 针对 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

@@ -0,0 +1,14 @@
+/**
+ * 针对 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/{src/env-react/emotion-register-globals.ts → env-react/emotion-register-globals.d.ts}

@@ -1,10 +1,7 @@
 /**
  * 把 emotion 的 css 函数注册为全局变量，就不用每次使用都手动引入了
  */
-import { css as cssValue } from '@emotion/react'
-
+import { css as cssValue } from '@emotion/react';
 declare global {
-  var css: typeof cssValue
+    var css: typeof cssValue;
 }
-
-globalThis.css = cssValue

package/env-react/emotion-register-globals.js

@@ -0,0 +1,5 @@
+/**
+ * 把 emotion 的 css 函数注册为全局变量，就不用每次使用都手动引入了
+ */
+import { css as cssValue } from '@emotion/react';
+globalThis.css = cssValue;

package/env-react/emotion.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 通过 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;