@tker/node-utils

Node.js 工具库，为构建工具和脚本开发提供常用的工具函数。整合了 chalk、consola、dayjs、execa、ora、prettier 等流行包，提供统一的 API 封装。

安装

pnpm add @tker/node-utils

使用方式

import {
  outputJSON,
  readJSON,
  getStagedFiles,
  generatorContentHash,
  findMonorepoRoot,
  getPackages,
  spinner,
  dateUtil,
  prettierFormat,
  colors,
  consola
} from '@tker/node-utils'

API

文件系统

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | outputJSON(filePath, data, spaces?) | filePath: string, data: any, spaces?: number | Promise<void> | 写入 JSON 文件（自动创建目录） | | readJSON(filePath) | filePath: string | Promise<any> | 读取 JSON 文件 | | ensureFile(filePath) | filePath: string | Promise<void> | 确保文件存在 |

// JSON 文件操作
await outputJSON('./config.json', { name: 'test', version: '1.0.0' }, 2)
const config = await readJSON('./config.json')
await ensureFile('./new-file.txt')

Git 操作

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | getStagedFiles() | - | Promise<string[]> | 获取 Git 暂存区文件列表 | | gitAdd | - | - | git add 命令（从 @changesets/git 重导出） |

// 获取暂存区文件
const stagedFiles = await getStagedFiles()
console.log('Staged files:', stagedFiles)

Monorepo 管理

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | findMonorepoRoot(cwd?) | cwd?: string | string | 查找 monorepo 根目录 | | getPackages() | - | Promise<{ packages: Package[] }> | 获取所有包信息 | | getPackagesSync() | - | { packages: Package[] } | 同步获取所有包信息 | | getPackage(pkgName) | pkgName: string | Promise<Package> | 获取指定包信息 |

// 查找 monorepo 根目录
const root = findMonorepoRoot()

// 获取所有包
const { packages } = await getPackages()

// 获取指定包
const myPkg = await getPackage('@tker/node-utils')
console.log(myPkg.packageJson.version)

内容哈希

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | generatorContentHash(content, hashLSize?) | content: string, hashLSize?: number | string | 生成 MD5 内容哈希 |

// 生成内容哈希（默认返回完整 MD5）
const hash = generatorContentHash('some content')

// 指定哈希长度
const shortHash = generatorContentHash('some content', 8)  // 返回前 8 位

Prettier 格式化

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | prettierFormat(filepath) | filepath: string | Promise<void> | 使用 Prettier 格式化文件 |

// 格式化文件
await prettierFormat('./src/index.ts')

Spinner 加载动画

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | spinner(options, callback) | SpinnerOptions, () => Promise<T> | Promise<T> | 执行异步任务并显示加载动画 |

// 使用 spinner 执行异步任务
const result = await spinner(
  {
    title: 'Installing dependencies...',
    successText: 'Dependencies installed!',
    failedText: 'Installation failed!'
  },
  async () => {
    // 执行异步操作
    await execa('pnpm', ['install'])
    return 'done'
  }
)

日期处理

| 导出 | 说明 | |------|------| | dateUtil | dayjs 实例（已配置 UTC、时区插件，默认上海时区） |

// 日期处理
const now = dateUtil().format('YYYY-MM-DD HH:mm:ss')
const utcTime = dateUtil().utc().format()

路径处理

| 函数 | 参数 | 返回值 | 说明 | |------|------|--------|------| | toPosixPath(pathname) | pathname: string | string | 将路径转换为 POSIX 风格 |

// Windows 路径转 POSIX
toPosixPath('C:\\Users\\test\\file.txt')  // 'C:/Users/test/file.txt'

模块处理

| 函数/类型 | 说明 | |------|------| | interopDefault(m) | 处理模块默认导出 | | Awaitable<T> | 类型定义：Promise<T> \| T |

// 处理模块默认导出
const module = await import('./config.js')
const config = interopDefault(module)

// Awaitable 类型
async function process(value: Awaitable<string>) {
  const result = await value  // 自动处理 Promise
}

重导出

以下包直接重导出，可直接使用：

| 导出 | 来源 | 说明 | |------|------|------| | colors | chalk | 终端颜色输出 | | consola | consola | 日志输出工具 | | execa | execa | 进程执行工具 | | fs | node:fs/promises | Node.js 文件系统 Promise API | | readPackageJSON | pkg-types | 读取 package.json | | PackageJson | pkg-types | package.json 类型定义 | | rimraf | rimraf | 递归删除文件/目录 |

// 使用重导出的包
import { colors, consola, execa, rimraf } from '@tker/node-utils'

console.log(colors.green('Success!'))
consola.info('Processing...')
await execa('node', ['script.js'])
await rimraf('./dist')

常量

| 常量 | 值 | 说明 | |------|------|------| | UNICODE.SUCCESS | ✓ | 成功图标 | | UNICODE.FAILURE | ✗ | 失败图标 |

import { UNICODE } from '@tker/node-utils'

console.log(UNICODE.SUCCESS)  // '✓'

License

MIT