@via-cli/npm-tools

A modern NPM package information fetcher with support for version checking and package.json retrieval

✨ Features

• 🚀 简单易用 - 构造函数初始化，链式调用
• 📦 完整信息 - 获取 package.json、版本号、包信息等
• 🔍 版本管理 - 检查最新版本、比较版本号、获取所有版本
• 📝 智能日志 - 可配置的日志输出，支持调试模式
• 🎯 TypeScript - 完整的类型定义支持
• 🌐 自定义源 - 支持自定义 NPM 注册表地址

📦 Installation

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

🚀 Quick Start

import { NpmClient } from '@via-cli/npm-tools';

// 创建客户端实例
const client = new NpmClient({
  pkgName: 'lodash',
  registry: 'https://registry.npmjs.org', // 可选，默认为 npmjs
  debug: false // 可选，是否启用调试日志
});

// 获取最新版本
const latestVersion = await client.getLatestVersion();
console.log('Latest version:', latestVersion);

// 获取 package.json
const packageJson = await client.getPackageJson();
console.log('Package.json:', packageJson);

// 获取所有版本
const allVersions = await client.getAllVersions();
console.log('All versions:', allVersions);

// 检查版本是否最新
const versionCheck = await client.isLatestVersion('4.17.21');
console.log('Is latest:', versionCheck.isLatest);
console.log('Needs update:', versionCheck.needsUpdate);

📖 API Reference

Constructor Options

interface NpmToolsOptions {
  /** 包名称 */
  pkgName: string;
  
  /** NPM 源地址，默认为 https://registry.npmjs.org */
  registry?: string;
  
  /** 是否启用调试模式，默认 false */
  debug?: boolean;
  
  /** 请求超时时间（毫秒），默认 30000 */
  timeout?: number;
}

Methods

getPackageInfo(): Promise<NpmPackageInfo>

获取 NPM 包的完整信息。

const packageInfo = await client.getPackageInfo();
console.log(packageInfo.name);
console.log(packageInfo.description);
console.log(packageInfo['dist-tags'].latest);

getPackageJson(version?: string): Promise<PackageVersion>

获取指定版本的 package.json 内容，不提供版本号则获取最新版本。

// 获取最新版本的 package.json
const latestPkg = await client.getPackageJson();

// 获取指定版本的 package.json
const specificPkg = await client.getPackageJson('4.17.21');
console.log(specificPkg.version);
console.log(specificPkg.dependencies);

getLatestVersion(): Promise<string>

获取包的最新版本号。

const latestVersion = await client.getLatestVersion();
console.log('Latest version:', latestVersion);

getAllVersions(): Promise<string[]>

获取包的所有版本号列表（从高到低排序）。

const allVersions = await client.getAllVersions();
console.log('Total versions:', allVersions.length);
console.log('Latest 5:', allVersions.slice(0, 5));

isLatestVersion(version: string): Promise<VersionCheckResult>

检查指定版本是否为最新版本。

const result = await client.isLatestVersion('4.17.21');
console.log('Current version:', result.currentVersion);
console.log('Latest version:', result.latestVersion);
console.log('Is latest:', result.isLatest);
console.log('Needs update:', result.needsUpdate);
console.log('Compare result:', result.compareResult); // 1, 0, or -1

返回值类型：

interface VersionCheckResult {
  currentVersion: string;
  latestVersion: string;
  isLatest: boolean;
  needsUpdate: boolean;
  compareResult: number; // 1: current > latest, 0: equal, -1: current < latest
}

compareVersions(version1: string, version2: string): number

比较两个版本号。

const result = client.compareVersions('4.17.21', '4.17.20');
// result === 1 (version1 > version2)
// result === 0 (version1 === version2)
// result === -1 (version1 < version2)

getSemverVersions(baseVersion: string): Promise<string[]>

获取符合 semver 规则的版本列表（匹配 ^baseVersion）。

// 获取所有与 4.17.0 兼容的版本
const compatibleVersions = await client.getSemverVersions('4.17.0');
console.log(compatibleVersions); // ['4.17.21', '4.17.20', '4.17.19', ...]

getPackageName(): string

获取包名称。

const pkgName = client.getPackageName();
console.log('Package name:', pkgName);

getRegistry(): string

获取注册表地址。

const registry = client.getRegistry();
console.log('Registry:', registry);

🎯 Usage Examples

Example 1: 基本用法

import { NpmClient } from '@via-cli/npm-tools';

async function main() {
  const client = new NpmClient({
    pkgName: 'vue',
    debug: true // 启用调试日志
  });

  // 获取最新版本
  const latest = await client.getLatestVersion();
  console.log(`Vue latest version: ${latest}`);

  // 获取所有版本
  const versions = await client.getAllVersions();
  console.log(`Total versions: ${versions.length}`);
}

main();

Example 2: 使用自定义 NPM 源

import { NpmClient } from '@via-cli/npm-tools';

const client = new NpmClient({
  pkgName: '@via-cli/type-tools',
  registry: 'http://npm.go-goal.com', // 自定义源
  debug: false
});

const packageInfo = await client.getPackageInfo();
console.log(packageInfo);

Example 3: 版本检查和更新提示

import { NpmClient } from '@via-cli/npm-tools';

async function checkForUpdates(pkgName: string, currentVersion: string) {
  const client = new NpmClient({ pkgName });
  
  const result = await client.isLatestVersion(currentVersion);
  
  if (result.needsUpdate) {
    console.log(`🚀 Update available for ${pkgName}!`);
    console.log(`   Current: ${result.currentVersion}`);
    console.log(`   Latest:  ${result.latestVersion}`);
  } else if (result.isLatest) {
    console.log(`✅ ${pkgName} is up to date!`);
  } else {
    console.log(`⚠️  You're using a newer version than the latest release.`);
  }
}

checkForUpdates('react', '18.2.0');

Example 4: 批量检查多个包

import { NpmClient } from '@via-cli/npm-tools';

async function checkMultiplePackages(packages: string[]) {
  const results = await Promise.all(
    packages.map(async (pkgName) => {
      const client = new NpmClient({ pkgName });
      const latest = await client.getLatestVersion();
      return { pkgName, latest };
    })
  );
  
  console.table(results);
}

checkMultiplePackages(['react', 'vue', 'angular', 'svelte']);

Example 5: 获取特定版本的依赖信息

import { NpmClient } from '@via-cli/npm-tools';

async function getDependencies(pkgName: string, version: string) {
  const client = new NpmClient({ pkgName });
  
  const packageJson = await client.getPackageJson(version);
  
  console.log(`Dependencies for ${pkgName}@${version}:`);
  console.log('Dependencies:', packageJson.dependencies);
  console.log('DevDependencies:', packageJson.devDependencies);
  console.log('PeerDependencies:', packageJson.peerDependencies);
}

getDependencies('typescript', '5.3.0');

🔧 Debug Mode

启用调试模式可以查看详细的请求和响应日志：

const client = new NpmClient({
  pkgName: 'lodash',
  debug: true // 启用调试模式
});

// 将输出详细的日志信息
await client.getPackageInfo();

输出示例：

[npm-tools] Client: Initialized NPM client for package: lodash
[npm-tools] Client: Registry: https://registry.npmjs.org
[npm-tools] Client: Timeout: 30000ms
[npm-tools] Client: Debug mode: enabled
[npm-tools] GetInfo: Fetching package info for: lodash
[npm-tools] GetInfo: Request URL: https://registry.npmjs.org/lodash
[npm-tools] GetInfo: Successfully fetched package info for: lodash
[npm-tools] GetInfo: Latest version: 4.17.21
[npm-tools] GetInfo: Total versions: 117

📄 License

MIT

🤝 Contributing

Contributions, issues and feature requests are welcome!

👤 Author

@via-cli team