@anjianshi/utils 2.9.1 → 3.0.0

package/src/lang/string.ts

@@ -0,0 +1,95 @@
+/**
+ * 字符串处理相关函数
+ */
+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: Record<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, radix = 10) {
+  const raw = parseInt(String(value), radix)
+  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
+}
+
+/**
+ * 返回人类可读的文件尺寸
+ * 来自：https://stackoverflow.com/a/14919494
+ *
+ * si: true 则使用 1000 进制，否则 1024 进制（默认 false）
+ * dp: 保留几位小数
+ */
+export function readableSize(bytes: number, 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<T>(json: string): T | undefined {
+  try {
+    return JSON.parse(json) as T
+  } catch (e) {
+    return undefined
+  }
+}

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/{lang/types.d.ts → src/lang/types.ts}

@@ -1,6 +1,7 @@
 /**
  * 对类型系统的辅助、补充
  */
+
 /**
  * 解决 TypeScript 中，数组字面量 [1, 'a'] 无法自动识别为 tuple 的问题
  *
@@ -11,17 +12,22 @@
  * https://github.com/microsoft/TypeScript/issues/27179
  * https://github.com/microsoft/TypeScript/issues/16656
  */
-export declare function tuple<T extends unknown[]>(...elements: T): T;
+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>;
+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>>;
+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;
+export type ReplaceFields<T, ReplaceT> = Omit<T, keyof ReplaceT> & ReplaceT
+
 /** 获取一个对象所有 value 的集合 */
-export type ValueOf<T> = T extends {
-    [_ in keyof T]: infer U;
-} ? U : never;
+export type ValueOf<T> = T extends { [_ in keyof T]: infer U } ? U : never
+
 /**
  * 获取指定类型的 key 的集合
  * 可以解决 keyof 无法正确获取继承了 plain object interface 的类型的 key 的问题
@@ -32,32 +38,46 @@ export type ValueOf<T> = T extends {
  * KnownKeys<MyType>     // 'a' | 'b'
  */
 export type KnownKeys<T> = ValueOf<{
-    [K in keyof T]: string extends K ? never : number extends K ? never : K;
-}>;
+  [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]>;
+export type ExcludePropertiesOfType<T, ExcludeValueT> = Pick<
+  T,
+  { [K in keyof T]: T[K] extends ExcludeValueT ? never : K }[keyof T]
+>
+
 /**
  * 生成不包含指定 key 的类型
  * 与 Omit<T, Keys> 的区别是
  */
-export type ExcludeKeys<T, ExcludeKeys> = Pick<T, {
-    [K in keyof T]: K extends ExcludeKeys ? never : K;
-}[keyof T]>;
+export type ExcludeKeys<T, ExcludeKeys> = Pick<
+  T,
+  { [K in keyof T]: K extends ExcludeKeys ? never : K }[keyof T]
+>
+
 /** 排除对象的方法（仅保留属性） */
-export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>;
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export type ExcluceMethods<T> = ExcludePropertiesOfType<T, Function>
+
 /**
  * 确认变量是否有值
  * 注意：空字符串和数字 0 也会判定为没有值
  */
-declare function truthy(value: string | number | boolean | null | undefined): value is string | number | true;
-declare function truthy<T>(value: T | string | number | boolean | null | undefined): value is T | string | number | true;
-export { truthy };
+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;
-};
+export type JSONData = number | boolean | string | null | JSONData[] | { [key: string]: JSONData }
+
 /**
  * 有些场景不适合用 undefined 判断一个变量是否被赋值（例如它允许被赋值成 undefined）
  * 此时可以用这个 symbol 来做判断。
@@ -65,4 +85,4 @@ export type JSONData = number | boolean | string | null | JSONData[] | {
  * if (value === noValue) console.log('未赋值')
  * else console.log('已赋值', value)
  */
-export declare const noValue: unique symbol;
+export const noValue = Symbol('no-value')

package/src/logging/adapt.ts

@@ -0,0 +1,49 @@
+import { getLogger, type Logger } from './index.js'
+
+interface Debug {
+  enable: (namespaces: string) => void
+  log: (...args: any[]) => any // eslint-disable-line @typescript-eslint/no-explicit-any
+}
+
+/**
+ * 适配 debug package
+ */
+export function adaptDebugLib(debugLib: Debug, enable = '', logger?: Logger) {
+  // 不在 localStorage 里记录 debugLib enable 状态，
+  // 以解决 web worker 里读不到 localStorage 而无法启用 debugLib 日志的问题
+  const emulate = {
+    storage: {
+      data: {} as Record<string, string>,
+      getItem(name: string) {
+        return emulate.storage.data[name]
+      },
+      setItem(name: string, value: string) {
+        emulate.storage.data[name] = value
+      },
+      removeItem(name: string) {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete emulate.storage.data[name]
+      },
+    },
+    save(namespaces: string) {
+      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/src/logging/formatters.ts

@@ -0,0 +1,23 @@
+/**
+ * 日志常用数据的格式化函数
+ */
+import { type LogInfo, LogLevel } from './index.js'
+
+const formatters = {
+  time(info: LogInfo) {
+    return info.time.format('HH:mm:ss.SSS')
+  },
+  datetime(info: LogInfo) {
+    return info.time.format('YY-MM-DD HH:mm:ss.SSS')
+  },
+  level(info: LogInfo) {
+    const map = {
+      [LogLevel.Debug]: 'debug',
+      [LogLevel.Info]: 'info',
+      [LogLevel.Warning]: 'warn',
+      [LogLevel.Error]: 'error',
+    }
+    return map[info.level]
+  },
+}
+export default formatters

package/src/logging/index.ts

@@ -0,0 +1,106 @@
+import dayjs, { type Dayjs } from 'dayjs'
+export { default as formatters } from './formatters.js'
+export * from './adapt.js'
+import { initDayJs } from '../init-dayjs.js'
+
+// 引入 logging 库会自动初始化 dayjs
+initDayJs()
+
+export enum LogLevel {
+  Debug = 1,
+  Info = 2,
+  Warning = 3,
+  Error = 4,
+}
+
+export const logLevelMap: Record<string, LogLevel> = {
+  debug: LogLevel.Debug,
+  info: LogLevel.Info,
+  warn: LogLevel.Warning,
+  warning: LogLevel.Warning,
+  err: LogLevel.Error,
+  error: LogLevel.Error,
+}
+
+export interface LogInfo {
+  logger: string // logger name；有多级 logger 的情况下，这是最初的 logger 名称
+  level: LogLevel
+  time: Dayjs
+  args: unknown[] // log content
+}
+
+export class LogHandler {
+  log(info: LogInfo) {} // eslint-disable-line @typescript-eslint/no-unused-vars
+}
+
+export class Logger {
+  level = LogLevel.Info
+  handlers = new Set<LogHandler>()
+
+  constructor(
+    public name = '',
+    public base: Logger | null = null, // 指定上级 logger，当前 logger 记录的日志也会传递给上级
+  ) {}
+
+  static getRealLevel(raw: LogLevel | string) {
+    if (typeof raw === 'string') {
+      raw = raw.toLowerCase()
+      if (logLevelMap[raw] === undefined) throw new Error('Not supported log level: ' + raw)
+      return logLevelMap[raw]!
+    }
+    return raw
+  }
+
+  setLevel(level: LogLevel | string) {
+    this.level = Logger.getRealLevel(level)
+  }
+
+  addHandler(handler: LogHandler) {
+    this.handlers.add(handler)
+  }
+
+  /**
+   * 创建一个以当前 logger 为 base 的 child logger
+   */
+  getChild(name: string) {
+    const fullname = this.name ? `${this.name}/${name}` : name
+    type Constructor = new (...args: ConstructorParameters<typeof Logger>) => Logger
+    // 这里加上 `as this` 才能让 TypeScript 判定，对继承了 Logger 的类调用此方法时，返回的是那个类而不是原始的 Logger 类的实例
+    return new (this.constructor as Constructor)(fullname, this) as this
+  }
+
+  log(level: LogLevel | string, args: unknown[]) {
+    level = Logger.getRealLevel(level)
+    this.logByInfo({ logger: this.name, level, time: dayjs(), args })
+  }
+  protected logByInfo(info: LogInfo) {
+    if (this.base) this.base.logByInfo(info)
+    if (this.level > info.level) return
+    for (const handler of this.handlers) {
+      handler.log(info)
+    }
+  }
+
+  debug(...args: any[]) {
+    this.log(LogLevel.Debug, args)
+  }
+  info(...args: any[]) {
+    this.log(LogLevel.Info, args)
+  }
+  warn(...args: any[]) {
+    this.log(LogLevel.Warning, args)
+  }
+  error(...args: any[]) {
+    this.log(LogLevel.Error, args)
+  }
+}
+
+/**
+ * 提供一套默认配置好的 logger
+ */
+const defaultLogger = new Logger()
+export { defaultLogger as logger }
+
+export function getLogger(name: string) {
+  return defaultLogger.getChild(name)
+}