A utility library for parsing and handling npm package arguments / 用於解析和處理 npm 套件參數的工具函式庫
A comprehensive utility library for parsing npm package arguments, providing enhanced functionality for yarn tools. This library wraps npm-package-arg with additional features like type guards, version extraction, flexible validation options, and TypeScript @types package name conversion.
一個全面的 npm 套件參數解析工具函式庫，為 yarn 工具提供增強功能。此函式庫封裝了 npm-package-arg，並提供額外功能如類型守衛、版本提取、靈活的驗證選項和 TypeScript @types 套件名稱轉換。
- Package Argument Parsing - Parse npm package arguments with validation / 解析 npm 套件參數並驗證
- Type Guards - Runtime type checking for different package types / 針對不同套件類型的執行時類型檢查
- Version Extraction - Extract semver from various package formats / 從各種套件格式提取語意版本
- @types Conversion - Convert package names to TypeScript @types format / 將套件名稱轉換為 TypeScript @types 格式
- Safe Parsing - Try-parse without throwing errors / 嘗試解析但不拋出錯誤
- Flexible Validation - Customizable validation options / 可自定義的驗證選項
- Assertion Functions - Comprehensive validation functions / 全面驗證函數
- TypeScript Support - Full TypeScript type definitions / 完整的 TypeScript 類型定義
yarn add @yarn-tool/npm-package-arg-util
yarn-tool add @yarn-tool/npm-package-arg-util
npm install @yarn-tool/npm-package-arg-util
import npa, { npa2, npaTry, npaTry2 } from '@yarn-tool/npm-package-arg-util';
const result = npa('lodash@4.17.21');
console.log(result.name);
console.log(result.type);
console.log(result.rawSpec);
console.log(result.fetchSpec);
const result2 = npa2('lodash@^4.17.0', {
allowedType: ['version', 'range']
});
const scoped = npa('@types/node@^18.0.0');
console.log(scoped.name);
console.log(scoped.scope);
console.log(scoped.escapedName);
const safe = npaTry('invalid-package-argument');
console.log(safe);
import { npa2, npaTry2 } from '@yarn-tool/npm-package-arg-util';
import type { IOptionsNpaUtil } from '@yarn-tool/npm-package-arg-util';
const options: IOptionsNpaUtil = {
where: process.cwd(),
shouldHasName: true,
allowedType: ['version', 'range', 'tag'],
};
const result = npa2('lodash@^4.17.0', options);
const gitRepo = npa2('user/repo#branch', {
shouldHasName: false
});
import {
isAliasResult,
isFileResult,
isRegistryResult,
isHostedGitResult,
isURLResult
} from '@yarn-tool/npm-package-arg-util/lib/detect';
const result = npa('lodash@^4.17.0');
if (isRegistryResult(result)) {
console.log('Package from npm registry / 來自 npm registry 的套件');
console.log('fetchSpec:', result.fetchSpec);
}
if (isHostedGitResult(result)) {
console.log('Package from GitHub/GitLab / 來自 GitHub/GitLab 的套件');
console.log('domain:', result.hosted?.domain);
}
import {
assertNpaResultHasName,
assertNpaResultByType,
assertNpaResultAll
} from '@yarn-tool/npm-package-arg-util/lib/assert';
const result = npa('lodash@4.17.21');
assertNpaResultHasName(result);
assertNpaResultByType(result, 'version');
assertNpaResultAll(result, {
shouldHasName: true,
allowedType: ['version', 'range'],
});
import { getSemverFromNpaResult } from '@yarn-tool/npm-package-arg-util';
const result = npa('lodash@^4.17.21');
const version = getSemverFromNpaResult(result);
console.log(version);
const alias = npa('my-lodash@npm:lodash@4.17.21');
const aliasVersion = getSemverFromNpaResult(alias);
console.log(aliasVersion);
const noVersion = npa('lodash');
console.log(getSemverFromNpaResult(noVersion));
import { parsePackageName } from '@yarn-tool/npm-package-arg-util/lib/parseArgvPkgName';
const parsed = parsePackageName('@types/node@^18.0.0');
console.log(parsed);
import { packageNameToTypes } from '@yarn-tool/npm-package-arg-util/lib/packageNameToTypes';
const types1 = packageNameToTypes('lodash');
console.log(types1.name);
const types2 = packageNameToTypes('@next/typescript');
console.log(types2.name);
const types3 = packageNameToTypes('@types/node');
console.log(types3.name);
import { generatePackageArg } from '@yarn-tool/npm-package-arg-util/lib/generatePackageArg';
const arg1 = generatePackageArg({ name: 'lodash' });
console.log(arg1);
const arg2 = generatePackageArg({ name: 'lodash', semver: '^4.17.0' }, true);
console.log(arg2);
| Function |
Description |
npa(arg, where?, options?) |
Parse npm package argument (legacy, strict name validation) / 解析 npm 套件參數（舊版，嚴格名稱驗證） |
npa2(arg, where?, options?) |
Parse npm package argument with flexible options / 使用靈活選項解析 npm 套件參數 |
npaTry(arg, where?, options?) |
Try parse without throwing (legacy) / 嘗試解析但不拋出錯誤（舊版） |
npaTry2(arg, where?, options?) |
Try parse without throwing (new) / 嘗試解析但不拋出錯誤（新版） |
getSemverFromNpaResult(result) |
Extract version from result / 從結果提取版本 |
interface IOptionsNpaUtil {
where?: string;
shouldHasName?: boolean;
allowedType?: IResultType[];
npa?: typeof _npa;
}
type IResult = AliasResult | FileResult | RegistryResult | HostedGitResult | URLResult;
type IResultAll = IResult | Result;
type IResultType = 'alias' | 'file' | 'directory' | 'version' | 'range' | 'tag' | 'git' | 'remote';
| Function |
Description |
isAliasResult(result) |
Check if alias package / 檢查是否為別名套件 |
isFileResult(result) |
Check if local file/directory / 檢查是否為本地檔案/目錄 |
isRegistryResult(result) |
Check if npm registry package / 檢查是否為 npm registry 套件 |
isHostedGitResult(result) |
Check if hosted git repo / 檢查是否為託管 git 儲存庫 |
isURLResult(result) |
Check if URL/remote / 檢查是否為 URL/遠端 |
| Function |
Description |
parsePackageName(name) |
Parse package name details / 解析套件名稱詳情 |
packageNameToTypes(name, prefix?) |
Convert to @types format / 轉換為 @types 格式 |
generatePackageArg(input, includeVersion?) |
Generate package argument / 生成套件參數 |
| Function |
Description |
assertNpaResultHasName(result) |
Assert result has a valid name / 斷言結果具有有效名稱 |
assertNpaResultByType(result, type) |
Assert result has specific type / 斷言結果具有特定類型 |
assertNpaResultAll(result, options?) |
Comprehensive validation / 全面驗證 |
| Type |
Example |
Description |
version |
pkg@1.2.3 |
Exact version / 精確版本 |
range |
pkg@^1.0.0 |
Version range / 版本範圍 |
tag |
pkg@latest |
Dist-tag / 分發標籤 |
git |
user/repo |
GitHub shorthand / GitHub 簡寫 |
git |
git+https://... |
Git URL / Git URL |
file |
./path/to/pkg.tar.gz |
Local file / 本地檔案 |
directory |
./path/to/dir |
Local directory / 本地目錄 |
alias |
pkg@npm:other@1.0.0 |
Package alias / 套件別名 |
remote |
https://...tar.gz |
Remote tarball / 遠端 tarball |
| Property |
Description |
type |
Result type string / 結果類型字串 |
name |
Package name (may be undefined for git URLs) / 套件名稱（git URL 可能為 undefined） |
escapedName |
URL-encoded name / URL 編碼的名稱 |
scope |
Package scope with @ prefix / 帶 @ 前綴的套件範圍 |
rawSpec |
Raw version specifier / 原始版本指定符 |
fetchSpec |
Normalized spec for fetching / 用於獲取的標準化規格 |
saveSpec |
Spec for saving to package.json / 用於保存到 package.json 的規格 |
raw |
Original input string / 原始輸入字串 |
where |
Base directory path / 基礎目錄路徑 |
hosted |
GitHost object (for hosted git) / GitHost 物件（用於託管 git） |
gitCommittish |
Git commit/branch/tag / git 提交/分支/標籤 |
gitRange |
Git semver range / git semver 範圍 |
gitSubdir |
Git subdirectory path / git 子目錄路徑 |
subSpec |
Sub-specification (for aliases) / 子規格（用於別名） |
ISC bluelovers
