@anjianshi/utils 2.5.0 → 2.7.0

package/README.md

@@ -0,0 +1,10 @@
+# Common JavaScript Utils
+
+## 依赖
+
+- `init-dayjs` 依赖 `dayjs`
+- `/logging` 依赖 `dayjs`，且会自动引用 `init-dayjs`
+- `/env-node/logging` 依赖 `chalk`
+- `/env-react/emotion` 依赖 `@emotion/*` 系列类库和 `react`
+- `/env-service/prisma` 依赖 `@prisma/client`
+- `/env-service/env-reader` 依赖 `dotenv`

package/eslint.config.cjs

@@ -0,0 +1,33 @@
+const globals = require('@anjianshi/presets-eslint-base/globals.cjs')
+const { limitFiles } = require('@anjianshi/presets-eslint-base/utils.cjs')
+
+const configs = [
+  ...require('@anjianshi/presets-eslint-base'),
+  ...require('@anjianshi/presets-eslint-typescript'),
+  ...limitFiles(
+    ['*.cjs', 'src/{env-node, env-service}/'],
+    require('@anjianshi/presets-eslint-node/exclusive.cjs'),
+  ),
+  ...limitFiles('src/env-browser/', {
+    languageOptions: {
+      globals: { ...globals.browser },
+    },
+  }),
+  ...limitFiles('src/env-react/', require('@anjianshi/presets-eslint-react/exclusive.cjs')),
+  ...limitFiles('src/env-service/prisma/', {
+    rules: {
+      // prisma 相关方法需要保证返回的是 PrismaPromise 而不能是经过 async function 转过的 Promise，所以不能把函数标记为 async function
+      '@typescript-eslint/promise-function-async': 'off',
+    },
+  }),
+  ...limitFiles('src/env-service/prisma/extensions/', {
+    rules: {
+      // prisma extension 需要用到 any 类型
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+    },
+  }),
+]
+module.exports = configs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjianshi/utils",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Common JavaScript Utils",
   "homepage": "https://github.com/anjianshi/js-packages/utils",
   "bugs": {
@@ -12,26 +12,37 @@
   "repository": "github:anjianshi/js-packages",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "access": "public",
+    "directory": "dist"
   },
   "type": "module",
+  "scripts": {
+    "watch": "npm run clear && tsc --watch",
+    "build": "npm run clear && tsc",
+    "clear": "rm -rf dist",
+    "prepublishOnly": "npm run build && node publish-prepare.cjs",
+    "postpublish": "rm dist/package.json",
+    "lint": "tsc --noEmit && node ../node_modules/eslint/bin/eslint.js './src/'"
+  },
   "main": "index.js",
   "dependencies": {
     "lodash": "^4.17.21"
   },
   "devDependencies": {
-    "@types/lodash": "^4.17.17",
-    "@types/node": "^22.15.21",
-    "@types/react": "^19.1.5",
-    "dotenv": "^16.5.0",
-    "redis": "^5.1.0",
+    "@anjianshi/presets-eslint-base": "workspace:*",
+    "@anjianshi/presets-eslint-node": "workspace:*",
+    "@anjianshi/presets-eslint-react": "workspace:*",
+    "@anjianshi/presets-eslint-typescript": "workspace:*",
+    "@anjianshi/presets-prettier": "workspace:*",
+    "@anjianshi/presets-typescript": "workspace:*",
+    "@types/lodash": "^4.17.20",
+    "@types/node": "^22.16.0",
+    "@types/react": "^19.1.8",
+    "dotenv": "^17.0.1",
+    "eslint": "^9.30.1",
+    "redis": "^5.5.6",
     "typescript": "^5.8.3",
-    "vconsole": "^3.15.1",
-    "@anjianshi/presets-eslint-node": "4.2.3",
-    "@anjianshi/presets-eslint-react": "4.2.3",
-    "@anjianshi/presets-prettier": "3.0.3",
-    "@anjianshi/presets-typescript": "3.2.4",
-    "@anjianshi/presets-eslint-typescript": "5.2.3"
+    "vconsole": "^3.15.1"
   },
   "peerDependencies": {
     "@emotion/react": "^11.14.0",
@@ -40,7 +51,7 @@
     "@prisma/client": "^6.8.2",
     "chalk": "^5.4.1",
     "dayjs": "^1.11.13",
-    "dotenv": "^16.5.0",
+    "dotenv": "^17.0.1",
     "react": "^19.1.0"
   },
   "peerDependenciesMeta": {
@@ -70,4 +81,4 @@
     }
   },
   "prettier": "@anjianshi/presets-prettier/prettierrc"
-}
+}

package/publish-prepare.cjs

@@ -0,0 +1,16 @@
+const fs = require('node:fs')
+const path = require('node:path')
+
+const base = path.resolve(__dirname, './')
+const dist = path.join(base, 'dist')
+
+const packageJSON = require(path.join(base, 'package.json'))
+delete packageJSON.publishConfig.directory
+delete packageJSON.scripts
+for (const [key, value] of Object.entries(packageJSON.dependencies)) {
+  packageJSON.dependencies[key] = value.replace('workspace:', 'workspace:../')
+}
+for (const [key, value] of Object.entries(packageJSON.devDependencies)) {
+  packageJSON.devDependencies[key] = value.replace('workspace:', 'workspace:../')
+}
+fs.writeFileSync(path.join(dist, 'package.json'), JSON.stringify(packageJSON, null, 2))

package/src/env-browser/device.ts

@@ -0,0 +1,62 @@
+/* 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/src/env-browser/global.ts

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

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

@@ -0,0 +1,13 @@
+/**
+ * 加载脚本文件
+ * 返回 Promise，成功则 resolve，失败 reject
+ */
+export default async function loadScript(url: string): Promise<void> {
+  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/src/env-browser/logging.ts

@@ -0,0 +1,58 @@
+/**
+ * 针对浏览器环境定制 logging
+ */
+import {
+  logger as defaultLogger,
+  type Logger,
+  type LogInfo,
+  LogLevel,
+  LogHandler,
+  formatters,
+} from '../logging/index.js'
+
+export * from '../logging/index.js'
+
+/**
+ * 实现向浏览器 console 输出日志
+ */
+export class ConsoleHandler extends LogHandler {
+  log(info: LogInfo) {
+    const color = (value = 'black') => `color: ${value};`
+    const prefix =
+      '%c' + [formatters.time(info), info.logger].map((v: string) => (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/）
+  private static readonly colors = [
+    '#dc9656',
+    '#7cafc2',
+    '#ba8baf',
+    '#a16946',
+    '#ab4642',
+    '#86c1b9',
+    '#a1b56c',
+    '#f7ca88',
+  ]
+  private static readonly colorMap = new Map<string, string>()
+  static getColor(name: string) {
+    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: Logger = defaultLogger) {
+  logger.addHandler(new ConsoleHandler())
+}

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

@@ -0,0 +1,54 @@
+import { type default as VConsole } from 'vconsole'
+
+/**
+ * 注册 VConsole 代码
+ * 此类库自己并不加载 VConsole，需使用者自行通过依赖或者 CDN 加载 VConsole 然后传给此类库
+ */
+let VConsoleLib: (new () => VConsole) | undefined
+
+export function registerVConsoleLib(lib: new () => VConsole) {
+  VConsoleLib = lib
+}
+
+/**
+ * 管理 VConsole 实例
+ */
+declare global {
+  interface Window {
+    VConsole: VConsole | null
+  }
+}
+
+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/src/env-node/crypto-random.ts

@@ -0,0 +1,30 @@
+/**
+ * 类似 lang/random.ts，但基于 Node.js 的 crypto 模块，提供密码级的随机数。
+ */
+import crypto from 'node:crypto'
+
+/**
+ * 返回随机数，包含 min 和 max
+ */
+export function getCryptoRandomInt(min: number, max: number) {
+  // 如果传入的 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<T>(choices: T[]) {
+  return choices[getCryptoRandomInt(0, choices.length - 1)]
+}

package/src/env-node/fs.ts

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

package/src/env-node/index.ts

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

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

@@ -0,0 +1,190 @@
+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 { type LogInfo, LogLevel, LogHandler, formatters } from '../../logging/index.js'
+
+/**
+ * 向 console 输出日志
+ */
+export class ConsoleHandler extends LogHandler {
+  log(info: LogInfo) {
+    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 readonly 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 readonly levelColors = {
+    [LogLevel.Debug]: chalk.whiteBright,
+    [LogLevel.Info]: chalk.white,
+    [LogLevel.Warning]: chalk.yellowBright,
+    [LogLevel.Error]: chalk.redBright,
+  }
+
+  // 可供 logger 选择的颜色
+  private static readonly loggerColors = [
+    'green',
+    'yellow',
+    'blue',
+    'magenta',
+    'cyan',
+    'greenBright',
+    'yellowBright',
+    'blueBright',
+    'magentaBright',
+    'cyanBright',
+  ] as const
+  private static readonly loggerColorMap = new Map<string, (typeof this.loggerColors)[number]>()
+  static getLoggerColor(logger: string) {
+    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 interface FileHandlerOptions {
+  dir: string // 日志存放目录 Logs directory
+  filePrefix: string // 日志文件名前缀 Prefix of the log file name
+  maxLength: number // 单条日志最长多少字符 Maximum length of a single log message
+  flushLength: number // 触发写入的缓存字符串数 Length of buffered strings that trigger a write operation
+  flushInterval: number // 缓存定时写入间隔（单位：ms），为 0 则所有日志立刻写入 Buffered strings write interval, 0 means all logs are written immediately.
+}
+
+export class FileHandler extends LogHandler {
+  readonly options: FileHandlerOptions
+
+  constructor(options?: Partial<FileHandlerOptions>) {
+    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: LogInfo) {
+    const { logger, args } = info
+    const prefix =
+      [
+        `[${formatters.datetime(info)}]`,
+        `[${formatters.level(info)}]`,
+        logger ? `[${logger}]` : '',
+      ].join('') + ' '
+
+    const itemStrings: string[] = []
+    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')
+  }
+
+  protected stringifyDataItem(item: unknown) {
+    // 去掉颜色控制字符
+    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
+  private buffer: string[] = []
+  private bufferSize = 0
+  private flushTimeoutId: NodeJS.Timeout | null = null
+
+  protected pushBuffer(...strings: string[]) {
+    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)
+    }
+  }
+
+  protected flush(sync?: boolean) {
+    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`,
+    )
+  }
+
+  protected initLogDir() {
+    if (!fs.existsSync(this.options.dir)) fs.mkdirSync(this.options.dir)
+  }
+
+  protected write(content: string, 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/src/env-node/logging/index.ts

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