@via-cli/common-tools

通用工具函数库，为 CLI 工具提供常用的实用功能，包括对象判断、路径处理、进程执行、NPM 操作和 URL 拼接等。

特性

• 🚀 现代化 ESM - 使用 ES 模块和 TypeScript
• 🛠️ 类型安全 - 完整的 TypeScript 类型定义
• 🧪 全面测试 - 使用 Vitest 进行单元测试
• 📦 模块化设计 - 按功能分类，支持按需引入
• 🔧 CLI 友好 - 专为命令行工具设计

安装

npm install @via-cli/common-tools
# 或
pnpm add @via-cli/common-tools
# 或
yarn add @via-cli/common-tools

使用

import {
  isObject,
  formatPath,
  exec,
  execAsync,
  sleep,
  spinnerStart,
  getNpmVersions,
  urlJoin
} from '@via-cli/common-tools';

API 文档

对象工具

isObject(value: unknown): boolean

判断给定值是否为纯对象。

console.log(isObject({})); // true
console.log(isObject([])); // false
console.log(isObject(null)); // false

路径工具

formatPath(filePath: string): string

格式化路径，将反斜杠转换为正斜杠。

console.log(formatPath('C:\\Users\\test')); // 'C:/Users/test'
console.log(formatPath('/home/user')); // '/home/user'

进程工具

exec(command: string, args?: string[], options?: ExecOptions)

执行命令并返回子进程。

const child = exec('node', ['--version']);
child.on('exit', (code) => {
  console.log(`Process exited with code: ${code}`);
});

execAsync(command: string, args?: string[], options?: ExecOptions): Promise<number>

异步执行命令并等待完成。

try {
  const exitCode = await execAsync('node', ['--version']);
  console.log(`Command completed with exit code: ${exitCode}`);
} catch (error) {
  console.error('Command failed:', error);
}

异步工具

sleep(timeout?: number): Promise<void>

延迟执行，默认 1000 毫秒。

async function example() {
  console.log('Start');
  await sleep(1000); // 等待1秒
  console.log('After 1 second');
}

命令行工具

spinnerStart(message: string, spinnerString?: string): SpinnerInstance

启动命令行旋转动画。

const spinner = spinnerStart('Loading...');
// 执行一些异步操作
setTimeout(() => {
  spinner.stop();
}, 3000);

NPM 工具

getNpmVersions(npmName: string, registry?: string): Promise<string[]>

获取 NPM 包的所有版本列表。

try {
  const versions = await getNpmVersions('vue');
  console.log('Available versions:', versions);
} catch (error) {
  console.error('Failed to get versions:', error);
}

getNpmInfo(npmName: string, registry?: string): Promise<any>

获取 NPM 包的详细信息。

try {
  const info = await getNpmInfo('vue');
  console.log('Package info:', info);
} catch (error) {
  console.error('Failed to get package info:', error);
}

getNpmSemverVersions(baseVersion: string, versions: string[]): string[]

根据基础版本从版本列表中获取符合 semver 规则的版本。

const versions = ['1.0.0', '1.1.0', '2.0.0'];
const compatibleVersions = getNpmSemverVersions('^1.0.0', versions);
console.log(compatibleVersions); // ['1.0.0', '1.1.0']

getNpmSemverVersion(baseVersion: string, versions: string[]): string | null

获取最高的符合 semver 规则的版本。

const versions = ['1.0.0', '1.1.0', '2.0.0'];
const latestVersion = getNpmSemverVersion('^1.0.0', versions);
console.log(latestVersion); // '1.1.0'

getDefaultRegistry(isOriginal?: boolean): string

获取默认的 NPM 注册表地址。

console.log(getDefaultRegistry()); // 'https://registry.npmjs.org'

URL 工具

urlJoin(...paths: string[]): string

拼接 URL 路径，自动处理斜杠。

console.log(urlJoin('https://api.example.com', 'v1', 'users')); 
// 'https://api.example.com/v1/users'

console.log(urlJoin('https://api.example.com/', '/v1/', '/users/'));
// 'https://api.example.com/v1/users/'

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 开发模式（监听变化）
pnpm dev

# 运行测试
pnpm test

# 监听测试
pnpm test:watch

# 生成测试覆盖率报告
pnpm test:coverage

# 清理构建文件
pnpm clean

技术栈

• TypeScript - 类型安全的开发体验
• ESM - 现代化的模块系统
• tsup - 快速的 TypeScript 构建工具
• Vitest - 快速的单元测试框架
• axios - HTTP 客户端
• semver - 语义化版本处理
• cli-spinner - 命令行旋转动画
• url-join - URL 拼接

许可证

MIT

更新日志

查看 CHANGELOG.md 了解详细的版本变更。