@anjianshi/utils 1.0.0

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 void console.warn('尚未传入 VConsole 对象，无法启动')
+  window.VConsole = new VConsoleLib()
+}
+
+export function destoryVConsole() {
+  if (!window.VConsole) return
+  window.VConsole.destroy()
+  window.VConsole = null
+}

package/src/env-node/.eslintrc.cjs

@@ -0,0 +1,4 @@
+/* eslint-env node */
+module.exports = {
+  extends: ['../../node_modules/@anjianshi/presets/eslint-node.js'],
+}

package/src/env-node/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Node 环境下的工具函数
+ */
+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 getFileDir(fileUrl: string | ImportMeta) {
+  return path.dirname(getFilePath(fileUrl))
+}

package/src/env-node/logging.ts

@@ -0,0 +1,202 @@
+/**
+ * 针对 Node.js 环境定制 logging
+ * 注意：使用此模块需要 chalk 依赖
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import chalk from 'chalk'
+import dayjs from 'dayjs'
+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 { 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}]`),
+      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()
+    this.initFlush()
+  }
+
+  // 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') return item
+    if (item instanceof Error) return item.stack ?? String(item)
+    try {
+      const json = JSON.stringify(item) as string | undefined
+      return json ?? String(json)
+    } catch (e: unknown) {
+      return String(item)
+    }
+  }
+
+  // Handle buffer
+  private buffer: string[] = []
+  private bufferSize = 0
+
+  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()
+  }
+
+  protected flush() {
+    if (this.buffer.length) {
+      const content = this.buffer.join('')
+      this.buffer = []
+      this.bufferSize = 0
+      this.write(content)
+    }
+  }
+
+  protected initFlush() {
+    if (this.options.flushInterval !== 0) {
+      setInterval(() => this.flush(), this.options.flushInterval)
+    }
+  }
+
+  // 文件系统交互 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) {
+    fs.appendFile(this.filepath, content, error => {
+      if (error) console.error('[logger] write failed: ' + String(error))
+    })
+  }
+}
+
+/**
+ * 预设的初始化行为
+ */
+export function initLogger(logger: Logger = defaultLogger) {
+  logger.addHandler(new ConsoleHandler())
+}

package/src/index.ts

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

package/src/init-dayjs.ts

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

package/src/lang/async.ts

@@ -0,0 +1,47 @@
+/**
+ * 异步行为相关函数
+ */
+
+/**
+ * 返回一个指定毫秒后 resolve 的 Promise
+ * 若指定了 resolveValue，则 Promise 最终会解析出此值
+ */
+async function sleep(ms: number): Promise<void>
+async function sleep<T>(ms: number, resolveValue: T): Promise<T>
+async function sleep<T>(ms: number, resolveValue?: T) {
+  return new Promise<T | void>(resolve => {
+    setTimeout(() => resolve(resolveValue), ms)
+  })
+}
+export { sleep }
+
+/**
+ * 给 Promise 增加时限。
+ * - 若 silent 为 false，超时时 reject 一个 TimeoutError
+ * - 若 silent 为 true，则超时后，promise 永远不会 resolve 或 reject
+ */
+export async function timeout<T>(
+  promise: Promise<T>,
+  timeoutMS: number,
+  silent = false,
+): Promise<T> {
+  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/src/lang/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js'
+export * from './string.js'
+export * from './object.js'
+export * from './time.js'
+export * from './async.js'

package/src/lang/object.ts

@@ -0,0 +1,28 @@
+/**
+ * 对两个对象进行浅比较
+ * 代码取自 react-addons-shallow-compare 包
+ */
+export function shallowEqual(objA: unknown, objB: unknown) {
+  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: unknown, y: unknown) {
+  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: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}

package/src/lang/string.ts

@@ -0,0 +1,62 @@
+/**
+ * 字符串处理相关函数
+ */
+import escapeRegExp from 'lodash/escapeRegExp.js'
+import padStart from 'lodash/padStart.js'
+
+/**
+ * 将数字字符串化，并在左侧填充 0 直到达到 length 参数指定的长度
+ * 若数字本身达到或超过此长度，则不填充
+ */
+export function zfill(num: number, length = 2) {
+  return padStart(String(num), length, '0')
+}
+
+/**
+ * 执行关键词匹配
+ * 成功返回 true；失败返回 false
+ */
+const kwCache: { [kw: string]: RegExp } = {} // 避免大量重复构建正则表达式影响性能
+export function keywordCompare(keyword: string, target: string) {
+  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: string, b: string) {
+  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: string | number, fallback?: number, redix = 10) {
+  const raw = parseInt(String(value), redix)
+  return isFinite(raw) ? raw : fallback ?? raw
+}
+
+/**
+ * 字符串解析成浮点数；若解析结果是 NaN，返回 fallback
+ */
+export function safeParseFloat(value: string | number, fallback: number) {
+  const raw = parseFloat(String(value))
+  return isFinite(raw) ? raw : fallback
+}

package/src/lang/time.ts

@@ -0,0 +1,19 @@
+/**
+ * 时间处理相关函数
+ */
+
+/**
+ * 返回指定时间长度的 毫秒数
+ */
+export function daysMS(n: number) {
+  return hoursMS(n * 24)
+}
+export function hoursMS(n: number) {
+  return minutesMS(n * 60)
+}
+export function minutesMS(n: number) {
+  return secondsMS(n * 60)
+}
+export function secondsMS(n: number) {
+  return n * 1000
+}

package/src/lang/types.ts

@@ -0,0 +1,138 @@
+/**
+ * 对类型系统的辅助、补充
+ */
+
+/**
+ * 解决 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<T extends unknown[]>(...elements: T) {
+  return elements
+}
+
+/**
+ * 将一个对象中的指定 key 设为必须的
+ */
+export type RequiredFields<T, K extends keyof T> = Omit<T, K> & Pick<Required<T>, K>
+
+/**
+ * 将一个对象中的指定 key 设为非必须的
+ */
+export type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+/**
+ * 用 ReplaceT 中的字段定义代替 T 中的
+ */
+export type ReplaceFields<T, ReplaceT> = Omit<T, keyof ReplaceT> & ReplaceT
+
+/**
+ * 获取一个对象所有 value 的集合
+ */
+export type ValueOf<T> = T extends { [_ in keyof T]: infer U } ? U : never
+
+/**
+ * 获取指定类型的 key 的集合
+ * 可以解决 keyof 无法正确获取继承了 plain object interface 的类型的 key 的问题
+ *
+ * interface Base { [key: string]: number }
+ * interface MyType extends Base { a: 1, b: 2 }
+ * keyof MyType          // string | number
+ * KnownKeys<MyType>     // 'a' | 'b'
+ */
+export type KnownKeys<T> = ValueOf<{
+  [K in keyof T]: string extends K ? never : number extends K ? never : K
+}>
+
+/**
+ * 排除对象中指定类型的项目
+ */
+export type ExcludePropertiesOfType<T, ExcludeValueT> = Pick<
+  T,
+  { [K in keyof T]: T[K] extends ExcludeValueT ? never : K }[keyof T]
+>
+
+/**
+ * 排除对象的方法（仅保留属性）
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>
+
+/**
+ * 所有“可能失败”的操作都可使用此类型作为返回值
+ */
+export interface Success<T = void> {
+  success: true
+  data: T
+}
+export interface Failed<ET = string> {
+  success: false
+  error: ET
+}
+export type MaySuccess<T = void, ET = string> = Success<T> | Failed<ET>
+
+function success(): Success
+function success<T>(data: T): Success<T>
+function success<T = void>(data?: T) {
+  return { success: true, data }
+}
+export { success }
+
+export function failed<ET>(error: ET): Failed<ET> {
+  return { success: false, error }
+}
+
+/**
+ * 若传入值为 success，格式化其 data；否则原样返回错误
+ * 支持传入会返回 MaySuccess 的 Promise
+ */
+function formatSuccess<T, ET, FT>(
+  item: MaySuccess<T, ET>,
+  formatter: (data: T) => FT,
+): MaySuccess<FT, ET>
+function formatSuccess<T, ET, FT>(
+  item: Promise<MaySuccess<T, ET>>,
+  formatter: (data: T) => FT,
+): Promise<MaySuccess<FT, ET>>
+function formatSuccess<T, ET, FT>(
+  item: MaySuccess<T, ET> | Promise<MaySuccess<T, ET>>,
+  formatter: (data: T) => FT,
+) {
+  if ('then' in item) return item.then(finalItem => formatSuccess(finalItem, formatter))
+  return item.success ? { ...item, data: formatter(item.data) } : item
+}
+export { formatSuccess }
+
+/**
+ * 确认变量是否有值
+ * 注意：空字符串和数字 0 也会判定为没有值
+ */
+function truthy(
+  value: string | number | boolean | null | undefined,
+): value is string | number | true
+function truthy<T>(
+  value: T | string | number | boolean | null | undefined,
+): value is T | string | number | true
+function truthy<T>(value: T | string | number | boolean | null | undefined) {
+  return value !== null && value !== undefined && value !== '' && value !== 0 && value !== false
+}
+export { truthy }
+
+/**
+ * 定义 JSON 数据
+ */
+export type JSONData = number | boolean | string | null | JSONData[] | { [key: string]: JSONData }
+
+/**
+ * 有些场景不适合用 undefined 判断一个变量是否被赋值（例如它允许被赋值成 undefined）
+ * 此时可以用这个 symbol 来做判断。
+ *
+ * if (value === noValue) console.log('未赋值')
+ * else console.log('已赋值', value)
+ */
+export const noValue = Symbol('no-value')