@viso/package-utils

一个功能丰富的工具库，提供文件操作、包管理、工作区管理、JSON/YAML 处理等常用功能。

功能特性

• 📁 文件操作: 文件的读取、写入、复制、删除等操作
• 📦 包管理: package.json 解析、依赖关系分析、包名处理
• 🏗️ 工作区管理: Monorepo 工作区的包发现和配置管理
• 📄 JSON 处理: JSON 的读取、写入、合并、验证、格式化
• 📝 YAML 处理: YAML 文件的读取和写入
• 🔍 文件匹配: 基于 glob 模式的文件搜索
• 🔤 字符串工具: 字符串处理和格式化功能
• 🗂️ 排序工具: 各种排序算法和工具

安装

npm install @viso/package-utils

核心模块

1. 文件操作 (file)

提供全面的文件系统操作功能：

import {
  checkFileExists,
  copyFile,
  ensureDir,
  findFiles,
  readFile,
  writeFile,
} from "@viso/package-utils";

// 读取文件
const content = await readFile("./config.json");

// 写入文件
await writeFile("./output.txt", "Hello World");

// 复制文件
await copyFile("./source.txt", "./dest.txt");

// 检查文件是否存在
const exists = await checkFileExists("./config.json");

// 查找文件
const files = await findFiles("**/*.ts", { cwd: "./src" });

// 确保目录存在
await ensureDir("./dist/assets");

2. 包管理 (package)

处理 npm 包相关的操作：

import {
  arrangeDependencyQueue,
  createDependencyGraph,
  extractPackageCdnDir,
  extractPackagePath,
  extractPackageType,
  readPackageJson,
} from "@viso/package-utils";

// 读取 package.json
const pkg = await readPackageJson("./package.json");

// 从包名提取信息
const type = extractPackageType("@company/package-name"); // 'company'
const path = extractPackagePath("@company/package-name"); // 'package-name'
const cdnDir = extractPackageCdnDir("@company/package-name"); // 'company/package-name'

// 创建依赖关系图
const graph = await createDependencyGraph(["./packages"]);

// 安排依赖队列
const queue = arrangeDependencyQueue(graph);

3. 工作区管理 (workspace)

Monorepo 工作区的管理功能：

import {
  createWorkspaceConfig,
  getWorkspacePatterns,
  getWorkspaceRootPath,
  listWorkspaceModules,
  listWorkspacePackageNames,
} from "@viso/package-utils";

// 获取工作区根路径
const rootPath = await getWorkspaceRootPath();

// 获取工作区模式
const patterns = await getWorkspacePatterns();

// 列出所有工作区模块
const modules = await listWorkspaceModules();

// 列出所有包名
const packageNames = await listWorkspacePackageNames();

// 创建工作区配置
const config = await createWorkspaceConfig({
  patterns: ["packages/*"],
  rootDir: process.cwd(),
});

4. JSON 处理 (json)

强大的 JSON 操作功能：

import {
  compressJson,
  extractJsonFields,
  filterJson,
  formatJson,
  mergeJson,
  readJson,
  validateJson,
  writeJson,
} from "@viso/package-utils";

// 读取 JSON 文件
const data = await readJson("./config.json");

// 写入 JSON 文件
await writeJson("./output.json", { name: "test" });

// 合并 JSON 对象
const merged = mergeJson(obj1, obj2);

// 格式化 JSON
const formatted = formatJson(data, { indent: 2 });

// 验证 JSON Schema
const isValid = validateJson(data, schema);

// 压缩 JSON（移除空白）
const compressed = compressJson(data);

// 过滤 JSON 字段
const filtered = filterJson(data, ["name", "version"]);

// 提取特定字段
const fields = extractJsonFields(data, ["dependencies"]);

5. YAML 处理 (yaml)

YAML 文件的读取和写入：

import { readYaml, writeYaml } from "@viso/package-utils";

// 读取 YAML 文件
const config = await readYaml("./config.yml");

// 写入 YAML 文件
await writeYaml("./output.yml", {
  name: "my-app",
  version: "1.0.0",
});

6. 文件匹配 (glob)

基于 glob 模式的文件搜索：

import { glob } from "@viso/package-utils";

// 搜索所有 TypeScript 文件
const tsFiles = await glob("**/*.ts", {
  cwd: "./src",
  ignore: ["**/*.test.ts"],
});

// 搜索特定目录下的文件
const configFiles = await glob("**/config.{js,json}");

7. 字符串工具 (string)

字符串处理和格式化：

import {
  camelCase,
  kebabCase,
  pascalCase,
  snakeCase,
} from "@viso/package-utils";

// 各种命名格式转换
const camel = camelCase("hello-world"); // 'helloWorld'
const kebab = kebabCase("HelloWorld"); // 'hello-world'
const pascal = pascalCase("hello_world"); // 'HelloWorld'
const snake = snakeCase("helloWorld"); // 'hello_world'

8. 排序工具 (sort)

排序算法和工具：

import { sortBy, sortPackages } from "@viso/package-utils";

// 按指定字段排序
const sorted = sortBy(array, "name");

// 按依赖关系排序包
const sortedPackages = sortPackages(packages);

类型定义

库提供了完整的 TypeScript 类型定义：

使用示例

构建工具集成

import {
  arrangeDependencyQueue,
  createDependencyGraph,
  listWorkspaceModules,
} from "@viso/package-utils";

async function buildAllPackages() {
  // 1. 获取所有工作区包
  const modules = await listWorkspaceModules();

  // 2. 创建依赖关系图
  const graph = await createDependencyGraph(modules.map((m) => m.path));

  // 3. 按依赖顺序排列构建队列
  const buildQueue = arrangeDependencyQueue(graph);

  // 4. 按顺序构建每个包
  for (const packageName of buildQueue) {
    console.log(`Building ${packageName}...`);
    // 执行构建逻辑
  }
}

配置文件处理

import {
  mergeJson,
  readJson,
  validateJson,
  writeJson,
} from "@viso/package-utils";

async function updateConfig() {
  // 读取现有配置
  const currentConfig = await readJson("./config.json");

  // 读取默认配置
  const defaultConfig = await readJson("./config.default.json");

  // 合并配置
  const mergedConfig = mergeJson(defaultConfig, currentConfig);

  // 验证配置
  const isValid = validateJson(mergedConfig, configSchema);

  if (isValid) {
    // 写入新配置
    await writeJson("./config.json", mergedConfig);
  }
}

文件批处理

import { ensureDir, glob, readFile, writeFile } from "@viso/package-utils";

async function processTemplates() {
  // 查找所有模板文件
  const templates = await glob("**/*.template", {
    cwd: "./templates",
  });

  // 确保输出目录存在
  await ensureDir("./dist");

  // 处理每个模板
  for (const template of templates) {
    const content = await readFile(template);
    const processed = content.replace("{{VERSION}}", "1.0.0");
    const outputPath = template.replace(".template", "");
    await writeFile(`./dist/${outputPath}`, processed);
  }
}

错误处理

所有异步函数都会在操作失败时抛出详细的错误信息：

try {
  const data = await readJson("./nonexistent.json");
} catch (error) {
  console.error("Failed to read JSON:", error.message);
}

依赖项

• ajv: JSON Schema 验证
• execa: 进程执行
• fast-glob: 高性能文件匹配
• fs-extra: 增强的文件系统操作
• js-yaml: YAML 解析
• lodash: 工具函数库
• yaml: YAML 处理

许可证

本项目使用 MIT 许可证。