@anjianshi/utils 3.0.0 → 3.0.2

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

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

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

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

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

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

@@ -1,190 +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 { 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

@@ -1,16 +0,0 @@
-/**
- * 针对 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())
-}

package/src/env-react/emotion.tsx

@@ -1,42 +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, withEmotionCache } from '@emotion/react'
-import { type CSSInterpolation, serializeStyles } from '@emotion/serialize'
-import { insertStyles } from '@emotion/utils'
-import { createContext, useContext, useCallback } from 'react'
-
-const CacheContext = createContext<EmotionCache | undefined>(undefined)
-export const useEmotionCache = () => useContext(CacheContext)
-
-export const EmotionCacheProvider = withEmotionCache(
-  ({ children }: { children: React.ReactNode }, cache: EmotionCache) => {
-    return <CacheContext.Provider value={cache}>{children}</CacheContext.Provider>
-  },
-)
-
-export function useEmotionClassName(): (...args: CSSInterpolation[]) => string {
-  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/src/env-react/hooks.ts

@@ -1,59 +0,0 @@
-import { useRef, useCallback } from 'react'
-
-/**
- * 生成一个 state 以及与其值同步的 ref
- */
-export function useStateWithRef<T>(initialValue: T | (() => T)) {
-  const [state, setState] = useState(initialValue)
-  const ref = useRef(state)
-
-  const setStateWithRef: typeof setState = useCallback((value: T | ((prevState: T) => T)) => {
-    setState(prevState => {
-      const newValue =
-        typeof value === 'function' ? (value as (prevState: T) => T)(prevState) : value
-      ref.current = newValue
-      return newValue
-    })
-  }, [])
-
-  return [state, setStateWithRef, ref] as const
-}
-
-/**
- * 在 useEffect() 中执行异步操作。
- * 因是异步运行，对清理机制的处理有所变化。
- *
- * 原本 useEffect() 中，通过返回一个函数来设置清理条件，在异步操作中不适用。
- * 此外，同步内容是一定会在执行完只后才有可能触发清理的，但异步内容有可能在运行完之前，依赖就已经变化，触发了清理。
- *
- * 这里通过一个 context 对象来应对异步的情况。
- * context.cancelled 值代表此次运行是否已被取消（清理），异步操作执行过程中如果发现此值变为 true，则可停止执行了。
- * context.onCancelled(() => {}) 可注册一个回调，此次执行被清理时触发。多次调用仅保留最后一次的回调。
- *
- * 注意：需要配置 ESLint react-hooks/exhaustive-deps 规则以保证 deps 参与依赖检查
- * 详见 https://react.dev/reference/eslint-plugin-react-hooks/lints/exhaustive-deps
- */
-export function useAsyncEffect(
-  callback: (context: AsyncEffectContext) => Promise<void>,
-  deps: unknown[] = [],
-) {
-  useEffect(() => {
-    let onCancel: (() => void) | null = null
-    const context = {
-      cancelled: false,
-      onCancel(callback: () => void) {
-        onCancel = callback
-      },
-    }
-
-    void callback(context)
-    return () => {
-      context.cancelled = true
-      if (onCancel) onCancel()
-    }
-  }, deps) // eslint-disable-line ts-react-hooks/exhaustive-deps
-}
-export interface AsyncEffectContext {
-  cancelled: boolean
-  onCancel: (callback: () => void) => void
-}

package/src/env-react/index.ts

@@ -1 +0,0 @@
-export * from './hooks.js'

package/src/env-react/react-register-globals.ts

@@ -1,53 +0,0 @@
-/**
- * 把 React Hooks 注册成全局变量，就不用每次使用都手动引入了
- * Hooks 列表见：https://react.dev/reference/react/hooks
- */
-
-import {
-  useState as useStateValue,
-  useReducer as useReducerValue,
-  useContext as useContextValue,
-  useRef as useRefValue,
-  useImperativeHandle as useImperativeHandleValue,
-  useEffect as useEffectValue,
-  useMemo as useMemoValue,
-  useCallback as useCallbackValue,
-  useTransition as useTransitionValue,
-  useDeferredValue as useDeferredValueValue,
-  useDebugValue as useDebugValueValue,
-  useId as useIdValue,
-  useSyncExternalStore as useSyncExternalStoreValue,
-  useActionState as useActionStateValue,
-} from 'react'
-
-declare global {
-  var useState: typeof useStateValue
-  var useReducer: typeof useReducerValue
-  var useContext: typeof useContextValue
-  var useRef: typeof useRefValue
-  var useImperativeHandle: typeof useImperativeHandleValue
-  var useEffect: typeof useEffectValue
-  var useMemo: typeof useMemoValue
-  var useCallback: typeof useCallbackValue
-  var useTransition: typeof useTransitionValue
-  var useDeferredValue: typeof useDeferredValueValue
-  var useDebugValue: typeof useDebugValueValue
-  var useId: typeof useIdValue
-  var useSyncExternalStore: typeof useSyncExternalStoreValue
-  var useActionState: typeof useActionStateValue
-}
-
-globalThis.useState = useStateValue
-globalThis.useReducer = useReducerValue
-globalThis.useContext = useContextValue
-globalThis.useRef = useRefValue
-globalThis.useImperativeHandle = useImperativeHandleValue
-globalThis.useEffect = useEffectValue
-globalThis.useMemo = useMemoValue
-globalThis.useCallback = useCallbackValue
-globalThis.useTransition = useTransitionValue
-globalThis.useDeferredValue = useDeferredValueValue
-globalThis.useDebugValue = useDebugValueValue
-globalThis.useId = useIdValue
-globalThis.useSyncExternalStore = useSyncExternalStoreValue
-globalThis.useActionState = useActionStateValue

package/src/env-service/controllers.ts

@@ -1,93 +0,0 @@
-/**
- * 把业务功能整理成各个 Controller，
- * 并整合成一个 controllers 对象方便外部引用和 Controller 之间互相引用。
- *
- * 支持自定义 Controller 类，例如把 context 中的内容定义成属性。
- */
-
-/*
-【使用范例】
-
-// 定制 Context 和 Controller
-interface MyContext {
-  prop1: number
-  prop2: string
-}
-class MyController<
-  AllControllers extends Record<string, AnyController<MyContext>>,
-> extends Controller<MyContext, AllControllers> {
-  get prop1() {
-    return this.context.prop1
-  }
-  get prop2() {
-    return this.context.prop2
-  }
-}
-
-// 实现 Controller 内容
-class C1 extends MyController<Controllers> {
-  someMethod() {
-    console.log(this.prop1)
-    console.log(this.controllers.c2.prop2)
-  }
-}
-class C2 extends MyController<Controllers> {}
-class C3 extends MyController<Controllers> {}
-
-// 生成 controllers 类型和对象
-export const controllerClasses = { c1: C1, c2: C2, c3: C3 }
-export type Controllers = ControllersFrom<MyContext, typeof controllerClasses>
-initializeControllers({ c1: C1, c2: C2, c3: C3 }, { prop1: 1, prop2: 2 })
-*/
-
-export type AnyObject = Record<string, unknown>
-export type AnyController<Context> = Controller<Context, any> // eslint-disable-line @typescript-eslint/no-explicit-any
-type AnyControllerClass<Context> = typeof Controller<Context, any> // eslint-disable-line @typescript-eslint/no-explicit-any
-type ControllerClassesFrom<Context, T extends AnyObject> = {
-  [K in keyof T]: T[K] extends AnyControllerClass<Context> ? T[K] : never
-}
-export type ControllersFrom<Context, T extends AnyObject> = {
-  [K in keyof T]: T[K] extends AnyControllerClass<Context> ? InstanceType<T[K]> : never
-}
-
-/**
- * Controller 基类
- */
-export class Controller<Context, AllControllers extends Record<string, AnyController<Context>>> {
-  constructor(
-    /** 调用其他 controllers */
-    protected readonly controllers: AllControllers,
-
-    protected readonly context: Context,
-
-    protected readonly name: string = this.constructor.name,
-  ) {}
-}
-
-/**
- * 传入 Controller 类列表，返回 controller 实例集合。
- * 为优化性能，每个 controller 只有在被使用到时才会实例化。
- */
-export function initializeControllers<Context, T extends AnyObject>(
-  controllerClasses: T,
-  context: Context,
-) {
-  type Classes = ControllerClassesFrom<Context, T>
-  type Controllers = ControllersFrom<Context, T>
-  const proxy = new Proxy({} as Controllers, {
-    get(controllers, prop) {
-      if (typeof prop !== 'string') return
-      if (prop in controllers) return controllers[prop]
-      if (prop in controllerClasses) {
-        const Class = controllerClasses[prop]! as typeof Controller<Context, Controllers>
-        controllers[prop as keyof Classes] = new Class(
-          proxy,
-          context,
-          prop,
-        ) as Controllers[keyof Classes]
-        return controllers[prop]
-      }
-    },
-  })
-  return proxy
-}