@lazy-node/semver-ampersand

支援 ampersand (&) 語法的 semver 範圍處理工具庫 / Semver range handling utilities with ampersand (&) syntax support

簡介 / Introduction

此模組擴展了標準 semver 套件的範圍處理功能，支援使用 & 符號來表示「且」的條件。這在處理 yarn 或 npm workspaces 的依賴版本時特別有用，因為某些情境下需要更明確的版本範圍表達方式。

This module extends the standard semver package's range handling with support for the & symbol to represent "AND" conditions. This is particularly useful when handling dependency versions in yarn or npm workspaces, where more explicit version range expressions are sometimes needed.

功能特色 / Features

• 🔗 Ampersand 支援 - 使用 & 符號組合多個版本條件 / Use & symbol to combine multiple version conditions
• ✅ satisfies - 檢查版本是否符合範圍 / Check if version satisfies range
• 🔍 maxSatisfying / minSatisfying - 找出最大/最小符合版本 / Find max/min satisfying version
• 📝 validRange - 驗證範圍字串是否有效 / Validate if range string is valid
• 🔄 simplifyRange - 簡化版本範圍 / Simplify version range
• 🏗️ Range 類別 - 類似 semver.Range 的增強版 / Enhanced Range class similar to semver.Range

安裝 / Installation

# 使用 yarn / Using yarn
yarn add @lazy-node/semver-ampersand

# 使用 yarn-tool / Using yarn-tool
yarn-tool add @lazy-node/semver-ampersand

# 使用 npm / Using npm
npm install @lazy-node/semver-ampersand

使用方式 / Usage

import { satisfies, validRange, maxSatisfying, Range } from '@lazy-node/semver-ampersand';

// 標準 semver 與 ampersand 語法皆可 / Both standard and ampersand syntax work
satisfies('1.2.3', '>=1.0.0 <2.0.0'); // true
satisfies('1.2.3', '>=1.0.0 & <2.0.0'); // true

// 驗證範圍是否有效 / Validate the range string
validRange('>=1.0.0 & <2.0.0'); // 回傳規範化後的範圍字串 / returns the normalized range string
validRange('>=1.0.0 & invalid'); // null

// 從版本清單挑選符合的版本 / Pick a satisfying version from a list
maxSatisfying(['1.0.0', '1.2.3', '2.0.0'], '>=1.0.0 & <2.0.0'); // '1.2.3'

// 重複使用同一個範圍 / Reuse one range instance
const range = new Range('>=1.0.0 & <2.0.0');
range.test('1.5.0'); // true

Ampersand (&) 語法說明 / Ampersand (&) Syntax Explanation

標準 semver 使用空格來表示「且」的條件，例如 >=1.0.0 <2.0.0。此模組額外支援使用 & 符號，讓範圍表達更明確：

Standard semver uses spaces to represent "AND" conditions, e.g., >=1.0.0 <2.0.0. This module additionally supports the & symbol for more explicit range expressions:

// 標準 semver 語法 / Standard semver syntax
'>=1.0.0 <2.0.0'

// Ampersand 語法（功能相同）/ Ampersand syntax (functionally equivalent)
'>=1.0.0 & <2.0.0'

API 文件 / API Documentation

satisfies(version, range, options?)

檢查版本是否符合指定的範圍。

Check if a version satisfies the specified range.

import { satisfies } from '@lazy-node/semver-ampersand';

// 標準 semver 範圍 / Standard semver range
satisfies('1.2.3', '>=1.0.0 <2.0.0'); // true
satisfies('2.0.0', '>=1.0.0 <2.0.0'); // false

// 使用 ampersand / Using ampersand
satisfies('1.2.3', '>=1.0.0 & <2.0.0'); // true
satisfies('1.2.3', '^1.0.0 & >=1.2.0'); // true

// 多條件組合 / Multiple conditions
satisfies('1.2.3', '>=1.0.0 & <2.0.0 || >=3.0.0'); // true

validRange(range, options?)

驗證範圍字串是否有效，返回規範化後的範圍或 null。

Validate if a range string is valid, returns normalized range or null.

import { validRange } from '@lazy-node/semver-ampersand';

validRange('>=1.0.0 & <2.0.0'); // 回傳規範化後的範圍字串 / Returns the normalized range string
validRange('invalid-range'); // null
validRange('>=1.0.0 & invalid'); // null

maxSatisfying(versions, range, options?)

從版本陣列中找出符合範圍的最大版本。

Find the maximum version that satisfies the range from an array of versions.

import { maxSatisfying } from '@lazy-node/semver-ampersand';

const versions = ['1.0.0', '1.2.3', '2.0.0', '2.1.0'];
maxSatisfying(versions, '>=1.0.0 & <2.0.0'); // '1.2.3'
maxSatisfying(versions, '^2.0.0'); // '2.1.0'

minSatisfying(versions, range, options?)

從版本陣列中找出符合範圍的最小版本。

Find the minimum version that satisfies the range from an array of versions.

import { minSatisfying } from '@lazy-node/semver-ampersand';

const versions = ['1.0.0', '1.2.3', '2.0.0', '2.1.0'];
minSatisfying(versions, '>=1.0.0 & <2.0.0'); // '1.0.0'
minSatisfying(versions, '^2.0.0'); // '2.0.0'

simplifyRange(versions, range, options?)

簡化版本範圍。

Simplify version range.

import { simplifyRange } from '@lazy-node/semver-ampersand';

const versions = ['1.0.0', '1.0.1', '1.0.2'];
simplifyRange(versions, '>=1.0.0 & <2.0.0');

handleAmpersandAndSpaces(range)

處理範圍字串中的 ampersand 和空格。

Handle ampersand and spaces in range string.

import { handleAmpersandAndSpaces } from '@lazy-node/semver-ampersand';

handleAmpersandAndSpaces('>=1.0.0 & <2.0.0');
// 返回處理後的範圍字串

Range 類別 / Range Class

增強版的 semver Range 類別，支援 ampersand 語法。

Enhanced semver Range class with ampersand syntax support.

import { Range } from '@lazy-node/semver-ampersand';

const range = new Range('>=1.0.0 & <2.0.0');

// 測試版本是否符合 / Test if version satisfies
range.test('1.2.3'); // true
range.test('2.0.0'); // false

// 存取範圍結構 / Access range structure
console.log(range.set); // 比較器集合

// 格式化輸出 / Format output
console.log(range.toString()); // '>=1.0.0 <2.0.0'

組態設定 / Configuration

此套件沒有設定檔 (Config File)，所有選項皆透過各函數的 options 參數傳遞，型別為 IOptions（繼承 semver.Options 與 semver.RangeOptions）。

This package has no config file; all options are passed through the options parameter of each function, typed as IOptions (extending semver.Options and semver.RangeOptions).

| 選項 / Option | 型別 / Type | 預設 / Default | 說明 / Description | | --- | --- | --- | --- | | loose | boolean | false | 寬鬆模式 (Loose Mode)，放寬版本字串解析規則 / Relax version string parsing rules | | includePrerelease | boolean | false | 將預發布版本 (Pre-release) 視為候選 / Include pre-release versions as candidates | | noAmpersand | boolean | false | 停用 ampersand (&) 支援，此時 & 會被視為無效字元 / Disable ampersand (&) support; & is then treated as an invalid character | | unsafeOptimize | boolean | false | 啟用不安全的比較器集合優化，可能改變邊界行為，請謹慎使用 / Enable unsafe comparator-set optimization; may alter edge behavior, use with caution |

import { satisfies, validRange } from '@lazy-node/semver-ampersand';

// noAmpersand: true → `&` 被視為無效字元，範圍回傳 null / `&` becomes an invalid character, so the range returns null
validRange('>=1.0.0 & <2.0.0', { noAmpersand: true }); // null
validRange('>=1.0.0 & <2.0.0'); // 回傳規範化後的範圍字串 / returns the normalized range string

// 允許預發布版本 / Include pre-release versions
satisfies('1.0.1-beta.1', '^1.0.0', { includePrerelease: true }); // true
satisfies('1.0.1-beta.1', '^1.0.0'); // false

// 布林值簡寫等同於 { loose: true } / Boolean shorthand equals `{ loose: true }`
satisfies('1.2.3', '>=1.0.0', true);

⚠️ noAmpersand 只在有傳遞選項的路徑（如 Range、validRange）生效；satisfies()、maxSatisfying() 等函式一律會先把 & 視為「且」處理。

⚠️ noAmpersand only takes effect on paths that forward options (such as Range and validRange); satisfies(), maxSatisfying(), etc. always treat & as "AND".

使用案例 / Use Cases

1. Workspaces 版本管理 / Workspace Version Management

import { satisfies, validRange } from '@lazy-node/semver-ampersand';

const workspaceDeps = {
  'package-a': '>=1.0.0 & <2.0.0',
  'package-b': '^2.0.0 & >=2.1.0',
};

Object.entries(workspaceDeps).forEach(([pkg, range]) => {
  if (validRange(range)) {
    console.log(`${pkg}: ${range} is valid`);
  }
});

2. 依賴版本檢查 / Dependency Version Checking

import { satisfies, maxSatisfying } from '@lazy-node/semver-ampersand';

const installedVersions = {
  'lodash': '4.17.21',
  'axios': '1.2.0',
};

const requiredRanges = {
  'lodash': '>=4.0.0 & <5.0.0',
  'axios': '^1.0.0',
};

Object.entries(requiredRanges).forEach(([pkg, range]) => {
  const version = installedVersions[pkg];
  if (version && !satisfies(version, range)) {
    console.log(`${pkg}@${version} does not satisfy ${range}`);
  }
});

3. 版本選擇 / Version Selection

import { maxSatisfying, minSatisfying } from '@lazy-node/semver-ampersand';

const availableVersions = [
  '1.0.0', '1.1.0', '1.2.0', 
  '2.0.0', '2.1.0', '3.0.0'
];

const range = '>=1.0.0 & <3.0.0';

console.log('Latest compatible:', maxSatisfying(availableVersions, range));
// '2.1.0'

console.log('Earliest compatible:', minSatisfying(availableVersions, range));
// '1.0.0'

4. 複雜範圍處理 / Complex Range Handling

import { Range, simplifyRange } from '@lazy-node/semver-ampersand';

// 複雜的版本需求 / Complex version requirements
const complexRange = '>=1.0.0 & <2.0.0 || >=3.0.0 & <4.0.0';

const range = new Range(complexRange);

// 檢查多個版本 / Check multiple versions
['1.5.0', '2.5.0', '3.5.0'].forEach(version => {
  console.log(`${version}: ${range.test(version)}`);
  // 1.5.0: true
  // 2.5.0: false
  // 3.5.0: true
});

與 semver 套件的差異 / Differences from semver Package

| 功能 / Feature | semver | @lazy-node/semver-ampersand | |---------------|----------|-------------------------------| | 標準範圍語法 / Standard range syntax | ✅ | ✅ | | Ampersand (&) 語法 / Ampersand syntax | ❌ | ✅ | | 空格表示「且」/ Space as "AND" | ✅ | ✅ | | Range 類別 / Range class | ✅ | ✅ (擴展版) | | 快取機制 / Caching | ✅ | ✅ |

相關套件 / Related Packages

• @lazy-node/semver-part - 版本部分比較工具 / Version part comparison utilities
• @lazy-node/semver-parse - semver 解析工具 / Semver parsing utilities
• semver - 語義化版本處理 / Semantic versioning

延伸閱讀 / Further Reading

• docs/semver-packages.md - @lazy-node/semver-* 系列套件總覽 / Overview of the @lazy-node/semver-* package series

授權 / License

ISC © bluelovers

貢獻 / Contributing

歡迎提交 Issue 和 Pull Request！

Issues and Pull Requests are welcome!

請前往 GitHub 貢獻。