@lazy-node/semver-ampersand 3.0.11 → 3.0.13

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.0.13](https://github.com/bluelovers/ws-yarn-workspaces/compare/@lazy-node/semver-ampersand@3.0.12...@lazy-node/semver-ampersand@3.0.13) (2026-10-12)
+
+
+
+### 🔖　Miscellaneous
+
+* . ([2ce14fc](https://github.com/bluelovers/ws-yarn-workspaces/commit/2ce14fcf8272584c51c4ba43b87a488f105c2f63))
+
+
+
+## [3.0.12](https://github.com/bluelovers/ws-yarn-workspaces/compare/@lazy-node/semver-ampersand@3.0.11...@lazy-node/semver-ampersand@3.0.12) (2026-10-12)
+
+
+
+### 📚　Documentation
+
+* add jsdoc ([9cb9b13](https://github.com/bluelovers/ws-yarn-workspaces/commit/9cb9b13eda8c357221ad1b754458aa9916eada22))
+
+
+### 🚨　Tests
+
+* **all:** 完善 node:test 遷移與測試案例優化 ([e38f263](https://github.com/bluelovers/ws-yarn-workspaces/commit/e38f26376a03520b39a54fea5794f27aecc4f424))
+* **snap:** update snapshots ([c9945a5](https://github.com/bluelovers/ws-yarn-workspaces/commit/c9945a5b9cd723d38ded2a69b83e2e83ecc3b524))
+* **test:** 將測試框架從 jest 遷移至 node:test ([3af9774](https://github.com/bluelovers/ws-yarn-workspaces/commit/3af9774964abc48083ec60b2021c1cec08874803))
+
+
+### 🛠　Build System
+
+* update build ([3186340](https://github.com/bluelovers/ws-yarn-workspaces/commit/3186340758172427cb1e9b8955f6fd677abac625))
+* **deps:** 更新測試腳本與依賴以支援 node:test ([f9c71c7](https://github.com/bluelovers/ws-yarn-workspaces/commit/f9c71c795c792c5c7ed9d613ce7e9c3c726c39d5))
+
+
+### ♻️　Chores
+
+* **deps:** 更新依賴版本並清理 npm-init2 腳本 ([82bf1e5](https://github.com/bluelovers/ws-yarn-workspaces/commit/82bf1e5d229759aa285205d81cf0651e4d3d9792))
+* **deps:** 更新各套件依賴版本 ([569f075](https://github.com/bluelovers/ws-yarn-workspaces/commit/569f0756189cdadf69955d8e388ac0a6a8988056))
+* **workspace:** 更新測試指令路徑與新增工作區搜尋選項 ([a80039d](https://github.com/bluelovers/ws-yarn-workspaces/commit/a80039dd8c691e047466966ffc8f8a4e2e31c03f))
+
+
+### 🔖　Miscellaneous
+
+* . ([e5788f8](https://github.com/bluelovers/ws-yarn-workspaces/commit/e5788f84551b870490a96d0a5d67d8d542481373))
+
+
+
 ## [3.0.11](https://github.com/bluelovers/ws-yarn-workspaces/compare/@lazy-node/semver-ampersand@3.0.10...@lazy-node/semver-ampersand@3.0.11) (2026-09-06)
 
 

package/README.md

@@ -11,6 +11,15 @@
 
 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
 
 ```bash
@@ -24,14 +33,26 @@ yarn-tool add @lazy-node/semver-ampersand
 npm install @lazy-node/semver-ampersand
 ```
 
-## 功能特色 / Features
+## 使用方式 / Usage
 
-- 🔗 **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
+```typescript
+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
 
@@ -79,7 +100,7 @@ Validate if a range string is valid, returns normalized range or `null`.
 ```typescript
 import { validRange } from '@lazy-node/semver-ampersand';
 
-validRange('>=1.0.0 & <2.0.0'); // true (返回規範化的範圍)
+validRange('>=1.0.0 & <2.0.0'); // 回傳規範化後的範圍字串 / Returns the normalized range string
 validRange('invalid-range'); // null
 validRange('>=1.0.0 & invalid'); // null
 ```
@@ -160,22 +181,38 @@ console.log(range.set); // 比較器集合
 console.log(range.toString()); // '>=1.0.0 <2.0.0'
 ```
 
-### 選項 / Options
+## 組態設定 / 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 |
 
 ```typescript
-interface IOptions extends semver.Options, semver.RangeOptions {
-  /**
-   * 停用 ampersand 處理 / Disable ampersand handling
-   */
-  noAmpersand?: boolean;
-  
-  /**
-   * 啟用不安全優化 / Enable unsafe optimization
-   */
-  unsafeOptimize?: boolean;
-}
+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
@@ -272,6 +309,10 @@ const range = new Range(complexRange);
 - [`@lazy-node/semver-parse`](../semver-parse) - semver 解析工具 / Semver parsing utilities
 - [`semver`](https://www.npmjs.com/package/semver) - 語義化版本處理 / Semantic versioning
 
+### 延伸閱讀 / Further Reading
+
+- [docs/semver-packages.md](../../../docs/semver-packages.md) - `@lazy-node/semver-*` 系列套件總覽 / Overview of the `@lazy-node/semver-*` package series
+
 ## 授權 / License
 
 ISC © bluelovers

package/lib/Range.d.ts

@@ -1,27 +1,138 @@
+/**
+ * 增強版 semver Range 類別
+ * Enhanced semver Range class
+ *
+ * 繼承 semver 的 Range，但刻意略過父層建構函式（super() 不帶參數），
+ * 改由 _inherit 自行正規化輸入，才能同時接受字串、Comparator、SemVer
+ * 與原生 Range 作為來源，並在搬移時保留原有的比較器集合以避免重複解析。
+ * Extends semver's Range but deliberately skips the parent constructor
+ * (`super()` takes no arguments), letting `_inherit` normalize the input so a
+ * string, Comparator, SemVer, or native Range can all serve as the source while
+ * an existing comparator set is carried over instead of re-parsed.
+ *
+ * @packageDocumentation
+ */
 import semverRange from 'semver/classes/range';
 import { IComparatorSet, IComparatorSetInput, IOptions, IOptionsOrLoose, ISemverRangeInput } from './types';
 import { Comparator } from 'semver';
 declare const SemverRange_base: typeof semverRange & (new () => semverRange);
+/**
+ * SemverRange 類別（對外以 Range 匯出）
+ * The SemverRange class (exported as `Range`)
+ *
+ * 特點：來源可為多種型別、支援 ampersand 語法、可重用既有比較器集合。
+ * Highlights: accepts several source types, supports ampersand syntax, and
+ * can reuse an existing comparator set.
+ *
+ * @template RAW - 原始輸入的型別 / Type of the raw input
+ *
+ * @example
+ * ```typescript
+ * const range = new Range('>=1.0.0 & <2.0.0');
+ * range.test('1.5.0'); // true
+ * range.toString(); // '>=1.0.0 <2.0.0'
+ * ```
+ */
 export declare class SemverRange<RAW extends ISemverRangeInput> extends SemverRange_base {
+    /** 呼叫端傳入的原始值，保留供除錯 / The original value passed in, kept for debugging */
     readonly rawSource?: RAW;
+    /** 規範化後的範圍字串 / Normalized range string */
     readonly raw: string;
+    /** 二維比較器集合（外層為 `||` 分隔的集合）/ Two-dimensional comparator set (outer level = `||` groups) */
     readonly set: IComparatorSet;
+    /** 解析後的選項 / Normalized options */
     readonly options: IOptions;
+    /** 是否為寬鬆模式 / Whether loose mode is on */
     readonly loose: boolean;
+    /** 是否納入預發布版本 / Whether pre-releases are included */
     readonly includePrerelease: boolean;
+    /** 快取的格式化結果，由 range getter 每次重算後寫入 / Cached formatted result, rewritten by the `range` getter on every access */
     protected readonly formatted: string;
+    /**
+     * 建立 Range 實例
+     * Create a Range instance
+     *
+     * @param rawSource - 範圍來源（字串、Comparator、SemVer、原生 Range）/ Range source (string, Comparator, SemVer, native Range)
+     * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+     * @throws {TypeError} 當比較器集合為空（整個範圍無效）時 / When the comparator set is empty (the whole range is invalid)
+     */
     constructor(rawSource: RAW, optionsOrLoose?: IOptionsOrLoose<IOptions>);
+    /**
+     * 把範圍字串切成二維比較器集合
+     * Turn a range string into a two-dimensional comparator set
+     *
+     * 以 `||` 分割成多個集合，各集合再解析為比較器；
+     * 空集合會被過濾（loose 模式下允許個別條件無效），
+     * 但若整個範圍都無效，外層的 assert 仍會拋錯。
+     * Split on `||` into groups, then parse each group into comparators; empty
+     * groups are dropped (loose mode tolerates invalid individual conditions),
+     * while a wholly invalid range still throws at the outer assert.
+     *
+     * @param range - 範圍字串 / Range string
+     * @param options - 選項 / Options
+     * @returns 比較器集合 / Comparator set
+     */
     protected _buildComparatorsSet(range: string, options: IOptions): IComparatorSetInput;
+    /**
+     * 解析單一（不含 `||`）的範圍字串
+     * Parse a single range string (without `||`)
+     *
+     * 這裡帶入 this.options，確保 ampersand 與空格的處理與建構時一致。
+     * Options are threaded through here so ampersand/space handling matches
+     * what the constructor did.
+     *
+     * @param range - 範圍字串 / Range string
+     * @returns 比較器陣列 / Comparator array
+     */
     parseRange(range: string): readonly Comparator[];
+    /**
+     * 從各種來源繼承範圍與選項
+     * Inherit range and options from any supported source
+     *
+     * 輸入為原生 semver Range 時：合併兩側選項，且僅在選項完全相同的情況下
+     * 直接沿用其 set；否則會重新解析（選項不同可能產生不同結果）。
+     * When the input is a native semver Range: options from both sides are
+     * merged, and its `set` is reused only when the merged options match
+     * exactly — otherwise it is re-parsed, since differing options can produce
+     * a different set.
+     *
+     * @param range - 範圍來源 / Range source
+     * @param options - 已正規化的選項 / Normalized options
+     * @returns 正規化後的 range、options 與（可能存在的）set / Normalized range, options, and (possibly) set
+     */
     protected _inherit(range: ISemverRangeInput, options: IOptions): {
         range: string;
         options: IOptions;
         set: readonly (readonly Comparator[])[];
     };
+    /**
+     * 把選項同步到實例上
+     * Sync options onto the instance
+     *
+     * options 寫入父層欄位後，再以 _copyOptions 複製 loose / includePrerelease
+     * 兩個常用欄位，避免每次取值都要翻閱 options 物件。
+     * After writing `options` to the parent field, `_copyOptions` mirrors the
+     * frequently used `loose` / `includePrerelease` fields so readers do not
+     * have to dig into the options object.
+     *
+     * @param options - 已正規化的選項 / Normalized options
+     */
     protected _inheritOptions(options: IOptions): void;
+    /**
+     * 取得格式化後的範圍字串
+     * Get the formatted range string
+     *
+     * 每次存取都從 set 重新組字串（而非取快取），因為 set 可能已被外部修改。
+     * The string is rebuilt from `set` on every access instead of being cached,
+     * because `set` may have been mutated externally.
+     */
     get range(): string;
     /**
      * Return '*' instead of '' so that truthiness works.
+     *
+     * 回傳 `*` 而非空字串，可讓 `if (range.toRangeString())` 這類真值判斷成立。
+     * Returning `*` instead of an empty string keeps truthiness checks such as
+     * `if (range.toRangeString())` working.
      */
     toRangeString(): string;
 }

package/lib/Range.js

@@ -2,6 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Range = exports.SemverRange = void 0;
 const tslib_1 = require("tslib");
+/**
+ * 增強版 semver Range 類別
+ * Enhanced semver Range class
+ *
+ * 繼承 semver 的 Range，但刻意略過父層建構函式（super() 不帶參數），
+ * 改由 _inherit 自行正規化輸入，才能同時接受字串、Comparator、SemVer
+ * 與原生 Range 作為來源，並在搬移時保留原有的比較器集合以避免重複解析。
+ * Extends semver's Range but deliberately skips the parent constructor
+ * (`super()` takes no arguments), letting `_inherit` normalize the input so a
+ * string, Comparator, SemVer, or native Range can all serve as the source while
+ * an existing comparator set is carried over instead of re-parsed.
+ *
+ * @packageDocumentation
+ */
 const range_1 = tslib_1.__importDefault(require("semver/classes/range"));
 const handleAmpersandAndSpaces_1 = require("./handleAmpersandAndSpaces");
 const stringifyComparators_1 = require("./util/stringifyComparators");
@@ -15,26 +29,83 @@ const fixComparatorSet_1 = require("./range/fixComparatorSet");
 const parseOptionsOrLoose_1 = require("./internal/parseOptionsOrLoose");
 const split_1 = require("./util/split");
 const parseRange_1 = require("./range/parseRange");
+/**
+ * SemverRange 類別（對外以 Range 匯出）
+ * The SemverRange class (exported as `Range`)
+ *
+ * 特點：來源可為多種型別、支援 ampersand 語法、可重用既有比較器集合。
+ * Highlights: accepts several source types, supports ampersand syntax, and
+ * can reuse an existing comparator set.
+ *
+ * @template RAW - 原始輸入的型別 / Type of the raw input
+ *
+ * @example
+ * ```typescript
+ * const range = new Range('>=1.0.0 & <2.0.0');
+ * range.test('1.5.0'); // true
+ * range.toString(); // '>=1.0.0 <2.0.0'
+ * ```
+ */
 class SemverRange extends (0, class_without_call_parent_constructor_1.classWithoutCallParentConstructor)(range_1.default) {
+    /**
+     * 建立 Range 實例
+     * Create a Range instance
+     *
+     * @param rawSource - 範圍來源（字串、Comparator、SemVer、原生 Range）/ Range source (string, Comparator, SemVer, native Range)
+     * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+     * @throws {TypeError} 當比較器集合為空（整個範圍無效）時 / When the comparator set is empty (the whole range is invalid)
+     */
     constructor(rawSource, optionsOrLoose) {
         // skip original semverRange constructor
         super();
+        // 統一選項格式，讓後續一律拿到物件形態的選項
+        // Normalize option shape so everything downstream sees an object
         optionsOrLoose = (0, parseOptionsOrLoose_1.parseOptionsOrLoose)(optionsOrLoose);
         let { range, options, set } = this._inherit(rawSource, optionsOrLoose);
+        /**
+         * 只有當正規化後的字串與呼叫端輸入不同時才記錄 rawSource，
+         * 否則保留 undefined，避免不必要的記憶體佔用。
+         * Record rawSource only when normalization changed the string;
+         * otherwise leave it undefined to avoid needless memory use.
+         */
         if (typeof rawSource === 'string' && range !== rawSource) {
             this.rawSource = rawSource;
         }
         this._inheritOptions(options);
+        /**
+         * 來源若已帶有比較器集合（例如搬移另一個 Range），
+         * 直接沿用，省下重新解析的成本。
+         * When the source already carries a comparator set (e.g. another
+         * Range being copied), reuse it instead of paying for a re-parse.
+         */
         if (!set) {
             set = this._buildComparatorsSet(range, options);
         }
         (0, assert_1.assertInvalidComparatorSet)(set, `Invalid SemVer Range: ${range}`);
+        // unsafeOptimize 才會真的做集合簡化，預設保持原樣以確保行為一致
+        // The set is only simplified under unsafeOptimize; by default it is kept
+        // as-is so behavior stays predictable
         set = (0, fixComparatorSet_1.fixComparatorSet)(set, options.unsafeOptimize);
         (0, assert_1.assertInvalidComparatorSet)(set);
         this.raw = range;
         this.set = set;
         this.format();
     }
+    /**
+     * 把範圍字串切成二維比較器集合
+     * Turn a range string into a two-dimensional comparator set
+     *
+     * 以 `||` 分割成多個集合，各集合再解析為比較器；
+     * 空集合會被過濾（loose 模式下允許個別條件無效），
+     * 但若整個範圍都無效，外層的 assert 仍會拋錯。
+     * Split on `||` into groups, then parse each group into comparators; empty
+     * groups are dropped (loose mode tolerates invalid individual conditions),
+     * while a wholly invalid range still throws at the outer assert.
+     *
+     * @param range - 範圍字串 / Range string
+     * @param options - 選項 / Options
+     * @returns 比較器集合 / Comparator set
+     */
     _buildComparatorsSet(range, options) {
         let comparatorsSet = (0, split_1.splitDoubleVerticalBar)(range)
             // map the range to a 2d array of comparators
@@ -45,9 +116,35 @@ class SemverRange extends (0, class_without_call_parent_constructor_1.classWitho
             .filter(c => c.length);
         return comparatorsSet;
     }
+    /**
+     * 解析單一（不含 `||`）的範圍字串
+     * Parse a single range string (without `||`)
+     *
+     * 這裡帶入 this.options，確保 ampersand 與空格的處理與建構時一致。
+     * Options are threaded through here so ampersand/space handling matches
+     * what the constructor did.
+     *
+     * @param range - 範圍字串 / Range string
+     * @returns 比較器陣列 / Comparator array
+     */
     parseRange(range) {
         return (0, parseRange_1.parseRange)(range, this.options);
     }
+    /**
+     * 從各種來源繼承範圍與選項
+     * Inherit range and options from any supported source
+     *
+     * 輸入為原生 semver Range 時：合併兩側選項，且僅在選項完全相同的情況下
+     * 直接沿用其 set；否則會重新解析（選項不同可能產生不同結果）。
+     * When the input is a native semver Range: options from both sides are
+     * merged, and its `set` is reused only when the merged options match
+     * exactly — otherwise it is re-parsed, since differing options can produce
+     * a different set.
+     *
+     * @param range - 範圍來源 / Range source
+     * @param options - 已正規化的選項 / Normalized options
+     * @returns 正規化後的 range、options 與（可能存在的）set / Normalized range, options, and (possibly) set
+     */
     _inherit(range, options) {
         let set;
         if (range instanceof range_1.default) {
@@ -58,11 +155,21 @@ class SemverRange extends (0, class_without_call_parent_constructor_1.classWitho
                 ...options,
             };
             options = (0, options_1._normalizeOptions)(options);
+            // 選項一致才可安全搬移 set，否則可能與新選項不相符
+            // The set may only be moved when options agree, otherwise it might
+            // not match the new options
             if ((0, options_1._isSameOptions)(range, options)) {
                 set = range.set;
             }
             range = range.raw;
         }
+        /**
+         * Comparator / SemVer 這兩種來源各自轉成可繼續解析的形態：
+         * Comparator 直接包成單元素集合，SemVer 則取其格式化字串。
+         * Comparator and SemVer sources are each converted into something
+         * parseable: a Comparator becomes a single-element set, a SemVer is
+         * reduced to its formatted string.
+         */
         if (range instanceof semver_2.Comparator) {
             set = [[range]];
             range = range.value;
@@ -70,10 +177,15 @@ class SemverRange extends (0, class_without_call_parent_constructor_1.classWitho
         else if (range instanceof semver_1.default) {
             range = range.format();
         }
+        // 有 set 但為空集合代表來源無效，提早拋錯避免帶到後續流程
+        // An existing-but-empty set means the source is invalid; fail fast
+        // instead of letting it travel further downstream
         if ((set === null || set === void 0 ? void 0 : set.length) === 0) {
             (0, assert_1.assertInvalidComparatorSet)(set);
         }
         options = (0, options_1._normalizeOptions)(options);
+        // 依選項決定是否把 & 視為「且」並整理空白
+        // Decide per options whether `&` means "AND" and tidy the whitespace
         range = (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(range, options);
         return {
             range,
@@ -81,10 +193,30 @@ class SemverRange extends (0, class_without_call_parent_constructor_1.classWitho
             set,
         };
     }
+    /**
+     * 把選項同步到實例上
+     * Sync options onto the instance
+     *
+     * options 寫入父層欄位後，再以 _copyOptions 複製 loose / includePrerelease
+     * 兩個常用欄位，避免每次取值都要翻閱 options 物件。
+     * After writing `options` to the parent field, `_copyOptions` mirrors the
+     * frequently used `loose` / `includePrerelease` fields so readers do not
+     * have to dig into the options object.
+     *
+     * @param options - 已正規化的選項 / Normalized options
+     */
     _inheritOptions(options) {
         this.options = options;
         (0, options_1._copyOptions)(this, options);
     }
+    /**
+     * 取得格式化後的範圍字串
+     * Get the formatted range string
+     *
+     * 每次存取都從 set 重新組字串（而非取快取），因為 set 可能已被外部修改。
+     * The string is rebuilt from `set` on every access instead of being cached,
+     * because `set` may have been mutated externally.
+     */
     // @ts-ignore
     get range() {
         // @ts-ignore
@@ -97,6 +229,10 @@ class SemverRange extends (0, class_without_call_parent_constructor_1.classWitho
     //	}
     /**
      * Return '*' instead of '' so that truthiness works.
+     *
+     * 回傳 `*` 而非空字串，可讓 `if (range.toRangeString())` 這類真值判斷成立。
+     * Returning `*` instead of an empty string keeps truthiness checks such as
+     * `if (range.toRangeString())` working.
      */
     toRangeString() {
         return (0, toRangeString_1.toRangeString)(this.range);

package/lib/Range.js.map

@@ -1 +1 @@
-{"version":3,"file":"Range.js","sourceRoot":"","sources":["Range.ts"],"names":[],"mappings":";;;;AAAA,yEAA+C;AAC/C,yEAAsE;AAQtE,sEAAsE;AACtE,2EAA2C;AAC3C,iGAA0F;AAC1F,mCAAoC;AACpC,6CAAkF;AAClF,yDAAsD;AACtD,0CAA2D;AAC3D,+DAA4D;AAC5D,wEAAqE;AACrE,wCAAsD;AACtD,mDAAgD;AAEhD,MAAa,WAA2C,SAAQ,IAAA,yEAAiC,EAAC,eAAW,CAAC;IAa7G,YAAY,SAAc,EAAE,cAA0C;QAErE,wCAAwC;QACxC,KAAK,EAAE,CAAC;QAER,cAAc,GAAG,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAC;QAErD,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAEvE,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,KAAK,KAAK,SAAS,EACxD,CAAC;YACA,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC5B,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAI,CAAC,GAAG,EACR,CAAC;YAEA,GAAG,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QAED,IAAA,mCAA0B,EAAC,GAAG,EAAE,yBAAyB,KAAK,EAAE,CAAC,CAAC;QAElE,GAAG,GAAG,IAAA,mCAAgB,EAAC,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;QAEpD,IAAA,mCAA0B,EAAC,GAAG,CAAC,CAAC;QAEhC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QAEf,IAAI,CAAC,MAAM,EAAE,CAAA;IACd,CAAC;IAES,oBAAoB,CAAC,KAAa,EAAE,OAAiB;QAE9D,IAAI,cAAc,GAAG,IAAA,8BAAsB,EAAC,KAAK,CAAC;YACjD,6CAA6C;aAC5C,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACrC,gDAAgD;YAChD,uEAAuE;YACvE,qEAAqE;aACpE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CACtB;QAED,OAAO,cAAc,CAAA;IACtB,CAAC;IAEQ,UAAU,CAAC,KAAa;QAEhC,OAAO,IAAA,uBAAU,EAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IACvC,CAAC;IAES,QAAQ,CAAC,KAAwB,EAAE,OAAiB;QAE7D,IAAI,GAAmB,CAAC;QAExB,IAAI,KAAK,YAAY,eAAW,EAChC,CAAC;YACA,OAAO,GAAG;gBACT,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;gBAC1C,GAAG,KAAK,CAAC,OAAO;gBAChB,GAAG,OAAO;aACV,CAAA;YAED,OAAO,GAAG,IAAA,2BAAiB,EAAC,OAAO,CAAC,CAAC;YAErC,IAAI,IAAA,wBAAc,EAAC,KAAK,EAAE,OAAO,CAAC,EAClC,CAAC;gBACA,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;YACjB,CAAC;YAED,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC;QACnB,CAAC;QAED,IAAI,KAAK,YAAY,mBAAU,EAC/B,CAAC;YACA,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YAChB,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;QACpB,CAAC;aACI,IAAI,KAAK,YAAY,gBAAM,EAChC,CAAC;YACA,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACxB,CAAC;QAED,IAAI,CAAA,GAAG,aAAH,GAAG,uBAAH,GAAG,CAAE,MAAM,MAAK,CAAC,EACrB,CAAC;YACA,IAAA,mCAA0B,EAAC,GAAG,CAAC,CAAC;QACjC,CAAC;QAED,OAAO,GAAG,IAAA,2BAAiB,EAAC,OAAO,CAAC,CAAC;QAErC,KAAK,GAAG,IAAA,mDAAwB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAEjD,OAAO;YACN,KAAK;YACL,OAAO;YACP,GAAG;SACH,CAAA;IACF,CAAC;IAES,eAAe,CAAC,OAAiB;QAEzC,IAA2B,CAAC,OAAO,GAAG,OAAO,CAAC;QAC/C,IAAA,sBAAY,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED,aAAa;IACb,IAAa,KAAK;QAEjB,aAAa;QACb,IAAI,CAAC,SAAS,GAAG,IAAA,8CAAuB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,SAAS,CAAA;IACtB,CAAC;IAEF,oBAAoB;IACpB,IAAI;IACJ,qBAAqB;IACrB,IAAI;IAEH;;OAEG;IACH,aAAa;QAEZ,OAAO,IAAA,6BAAa,EAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACjC,CAAC;CAED;AA9ID,kCA8IC;AAEuB,4BAAK;AAE7B,kBAAe,WAAW,CAAA","sourcesContent":["import semverRange from 'semver/classes/range';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\nimport {\n\tIComparatorSet,\n\tIComparatorSetInput,\n\tIOptions,\n\tIOptionsOrLoose,\n\tISemverRangeInput,\n} from './types';\nimport { stringifyComparatorsSet } from './util/stringifyComparators';\nimport SemVer from 'semver/classes/semver';\nimport { classWithoutCallParentConstructor } from 'class-without-call-parent-constructor';\nimport { Comparator } from 'semver';\nimport { _copyOptions, _isSameOptions, _normalizeOptions } from './range/options';\nimport { toRangeString } from './range/toRangeString';\nimport { assertInvalidComparatorSet } from './util/assert';\nimport { fixComparatorSet } from './range/fixComparatorSet';\nimport { parseOptionsOrLoose } from './internal/parseOptionsOrLoose';\nimport { splitDoubleVerticalBar } from './util/split';\nimport { parseRange } from './range/parseRange';\n\nexport class SemverRange<RAW extends ISemverRangeInput> extends classWithoutCallParentConstructor(semverRange)\n{\n\treadonly rawSource?: RAW;\n\n\toverride readonly raw: string;\n\toverride readonly set: IComparatorSet;\n\n\toverride readonly options: IOptions;\n\toverride readonly loose: boolean;\n\toverride readonly includePrerelease: boolean;\n\n\tprotected readonly formatted: string;\n\n\tconstructor(rawSource: RAW, optionsOrLoose?: IOptionsOrLoose<IOptions>)\n\t{\n\t\t// skip original semverRange constructor\n\t\tsuper();\n\n\t\toptionsOrLoose = parseOptionsOrLoose(optionsOrLoose);\n\n\t\tlet { range, options, set } = this._inherit(rawSource, optionsOrLoose);\n\n\t\tif (typeof rawSource === 'string' && range !== rawSource)\n\t\t{\n\t\t\tthis.rawSource = rawSource;\n\t\t}\n\n\t\tthis._inheritOptions(options);\n\n\t\tif (!set)\n\t\t{\n\n\t\t\tset = this._buildComparatorsSet(range, options);\n\t\t}\n\n\t\tassertInvalidComparatorSet(set, `Invalid SemVer Range: ${range}`);\n\n\t\tset = fixComparatorSet(set, options.unsafeOptimize);\n\n\t\tassertInvalidComparatorSet(set);\n\n\t\tthis.raw = range;\n\t\tthis.set = set;\n\n\t\tthis.format()\n\t}\n\n\tprotected _buildComparatorsSet(range: string, options: IOptions): IComparatorSetInput\n\t{\n\t\tlet comparatorsSet = splitDoubleVerticalBar(range)\n\t\t\t// map the range to a 2d array of comparators\n\t\t\t.map(range => this.parseRange(range))\n\t\t\t// throw out any comparator lists that are empty\n\t\t\t// this generally means that it was not a valid range, which is allowed\n\t\t\t// in loose mode, but will still throw if the WHOLE range is invalid.\n\t\t\t.filter(c => c.length)\n\t\t;\n\n\t\treturn comparatorsSet\n\t}\n\n\toverride parseRange(range: string)\n\t{\n\t\treturn parseRange(range, this.options)\n\t}\n\n\tprotected _inherit(range: ISemverRangeInput, options: IOptions)\n\t{\n\t\tlet set: IComparatorSet;\n\n\t\tif (range instanceof semverRange)\n\t\t{\n\t\t\toptions = {\n\t\t\t\tloose: range.loose,\n\t\t\t\tincludePrerelease: range.includePrerelease,\n\t\t\t\t...range.options,\n\t\t\t\t...options,\n\t\t\t}\n\n\t\t\toptions = _normalizeOptions(options);\n\n\t\t\tif (_isSameOptions(range, options))\n\t\t\t{\n\t\t\t\tset = range.set;\n\t\t\t}\n\n\t\t\trange = range.raw;\n\t\t}\n\n\t\tif (range instanceof Comparator)\n\t\t{\n\t\t\tset = [[range]];\n\t\t\trange = range.value\n\t\t}\n\t\telse if (range instanceof SemVer)\n\t\t{\n\t\t\trange = range.format();\n\t\t}\n\n\t\tif (set?.length === 0)\n\t\t{\n\t\t\tassertInvalidComparatorSet(set);\n\t\t}\n\n\t\toptions = _normalizeOptions(options);\n\n\t\trange = handleAmpersandAndSpaces(range, options);\n\n\t\treturn {\n\t\t\trange,\n\t\t\toptions,\n\t\t\tset,\n\t\t}\n\t}\n\n\tprotected _inheritOptions(options: IOptions)\n\t{\n\t\t(this as any as semverRange).options = options;\n\t\t_copyOptions(this, options);\n\t}\n\n\t// @ts-ignore\n\toverride get range()\n\t{\n\t\t// @ts-ignore\n\t\tthis.formatted = stringifyComparatorsSet(this.set);\n\t\treturn this.formatted\n\t}\n\n//\toverride format()\n//\t{\n//\t\treturn this.range\n//\t}\n\n\t/**\n\t * Return '*' instead of '' so that truthiness works.\n\t */\n\ttoRangeString()\n\t{\n\t\treturn toRangeString(this.range)\n\t}\n\n}\n\nexport { SemverRange as Range }\n\nexport default SemverRange\n"]}
+{"version":3,"file":"Range.js","sourceRoot":"","sources":["Range.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 增強版 semver Range 類別\n * Enhanced semver Range class\n *\n * 繼承 semver 的 Range，但刻意略過父層建構函式（super() 不帶參數），\n * 改由 _inherit 自行正規化輸入，才能同時接受字串、Comparator、SemVer\n * 與原生 Range 作為來源，並在搬移時保留原有的比較器集合以避免重複解析。\n * Extends semver's Range but deliberately skips the parent constructor\n * (`super()` takes no arguments), letting `_inherit` normalize the input so a\n * string, Comparator, SemVer, or native Range can all serve as the source while\n * an existing comparator set is carried over instead of re-parsed.\n *\n * @packageDocumentation\n */\nimport semverRange from 'semver/classes/range';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\nimport {\n\tIComparatorSet,\n\tIComparatorSetInput,\n\tIOptions,\n\tIOptionsOrLoose,\n\tISemverRangeInput,\n} from './types';\nimport { stringifyComparatorsSet } from './util/stringifyComparators';\nimport SemVer from 'semver/classes/semver';\nimport { classWithoutCallParentConstructor } from 'class-without-call-parent-constructor';\nimport { Comparator } from 'semver';\nimport { _copyOptions, _isSameOptions, _normalizeOptions } from './range/options';\nimport { toRangeString } from './range/toRangeString';\nimport { assertInvalidComparatorSet } from './util/assert';\nimport { fixComparatorSet } from './range/fixComparatorSet';\nimport { parseOptionsOrLoose } from './internal/parseOptionsOrLoose';\nimport { splitDoubleVerticalBar } from './util/split';\nimport { parseRange } from './range/parseRange';\n\n/**\n * SemverRange 類別（對外以 Range 匯出）\n * The SemverRange class (exported as `Range`)\n *\n * 特點：來源可為多種型別、支援 ampersand 語法、可重用既有比較器集合。\n * Highlights: accepts several source types, supports ampersand syntax, and\n * can reuse an existing comparator set.\n *\n * @template RAW - 原始輸入的型別 / Type of the raw input\n *\n * @example\n * ```typescript\n * const range = new Range('>=1.0.0 & <2.0.0');\n * range.test('1.5.0'); // true\n * range.toString(); // '>=1.0.0 <2.0.0'\n * ```\n */\nexport class SemverRange<RAW extends ISemverRangeInput> extends classWithoutCallParentConstructor(semverRange)\n{\n\t/** 呼叫端傳入的原始值，保留供除錯 / The original value passed in, kept for debugging */\n\treadonly rawSource?: RAW;\n\n\t/** 規範化後的範圍字串 / Normalized range string */\n\toverride readonly raw: string;\n\n\t/** 二維比較器集合（外層為 `||` 分隔的集合）/ Two-dimensional comparator set (outer level = `||` groups) */\n\toverride readonly set: IComparatorSet;\n\n\t/** 解析後的選項 / Normalized options */\n\toverride readonly options: IOptions;\n\n\t/** 是否為寬鬆模式 / Whether loose mode is on */\n\toverride readonly loose: boolean;\n\n\t/** 是否納入預發布版本 / Whether pre-releases are included */\n\toverride readonly includePrerelease: boolean;\n\n\t/** 快取的格式化結果，由 range getter 每次重算後寫入 / Cached formatted result, rewritten by the `range` getter on every access */\n\tprotected readonly formatted: string;\n\n\t/**\n\t * 建立 Range 實例\n\t * Create a Range instance\n\t *\n\t * @param rawSource - 範圍來源（字串、Comparator、SemVer、原生 Range）/ Range source (string, Comparator, SemVer, native Range)\n\t * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n\t * @throws {TypeError} 當比較器集合為空（整個範圍無效）時 / When the comparator set is empty (the whole range is invalid)\n\t */\n\tconstructor(rawSource: RAW, optionsOrLoose?: IOptionsOrLoose<IOptions>)\n\t{\n\t\t// skip original semverRange constructor\n\t\tsuper();\n\n\t\t// 統一選項格式，讓後續一律拿到物件形態的選項\n\t\t// Normalize option shape so everything downstream sees an object\n\t\toptionsOrLoose = parseOptionsOrLoose(optionsOrLoose);\n\n\t\tlet { range, options, set } = this._inherit(rawSource, optionsOrLoose);\n\n\t\t/**\n\t\t * 只有當正規化後的字串與呼叫端輸入不同時才記錄 rawSource，\n\t\t * 否則保留 undefined，避免不必要的記憶體佔用。\n\t\t * Record rawSource only when normalization changed the string;\n\t\t * otherwise leave it undefined to avoid needless memory use.\n\t\t */\n\t\tif (typeof rawSource === 'string' && range !== rawSource)\n\t\t{\n\t\t\tthis.rawSource = rawSource;\n\t\t}\n\n\t\tthis._inheritOptions(options);\n\n\t\t/**\n\t\t * 來源若已帶有比較器集合（例如搬移另一個 Range），\n\t\t * 直接沿用，省下重新解析的成本。\n\t\t * When the source already carries a comparator set (e.g. another\n\t\t * Range being copied), reuse it instead of paying for a re-parse.\n\t\t */\n\t\tif (!set)\n\t\t{\n\n\t\t\tset = this._buildComparatorsSet(range, options);\n\t\t}\n\n\t\tassertInvalidComparatorSet(set, `Invalid SemVer Range: ${range}`);\n\n\t\t// unsafeOptimize 才會真的做集合簡化，預設保持原樣以確保行為一致\n\t\t// The set is only simplified under unsafeOptimize; by default it is kept\n\t\t// as-is so behavior stays predictable\n\t\tset = fixComparatorSet(set, options.unsafeOptimize);\n\n\t\tassertInvalidComparatorSet(set);\n\n\t\tthis.raw = range;\n\t\tthis.set = set;\n\n\t\tthis.format()\n\t}\n\n\t/**\n\t * 把範圍字串切成二維比較器集合\n\t * Turn a range string into a two-dimensional comparator set\n\t *\n\t * 以 `||` 分割成多個集合，各集合再解析為比較器；\n\t * 空集合會被過濾（loose 模式下允許個別條件無效），\n\t * 但若整個範圍都無效，外層的 assert 仍會拋錯。\n\t * Split on `||` into groups, then parse each group into comparators; empty\n\t * groups are dropped (loose mode tolerates invalid individual conditions),\n\t * while a wholly invalid range still throws at the outer assert.\n\t *\n\t * @param range - 範圍字串 / Range string\n\t * @param options - 選項 / Options\n\t * @returns 比較器集合 / Comparator set\n\t */\n\tprotected _buildComparatorsSet(range: string, options: IOptions): IComparatorSetInput\n\t{\n\t\tlet comparatorsSet = splitDoubleVerticalBar(range)\n\t\t\t// map the range to a 2d array of comparators\n\t\t\t.map(range => this.parseRange(range))\n\t\t\t// throw out any comparator lists that are empty\n\t\t\t// this generally means that it was not a valid range, which is allowed\n\t\t\t// in loose mode, but will still throw if the WHOLE range is invalid.\n\t\t\t.filter(c => c.length)\n\t\t;\n\n\t\treturn comparatorsSet\n\t}\n\n\t/**\n\t * 解析單一（不含 `||`）的範圍字串\n\t * Parse a single range string (without `||`)\n\t *\n\t * 這裡帶入 this.options，確保 ampersand 與空格的處理與建構時一致。\n\t * Options are threaded through here so ampersand/space handling matches\n\t * what the constructor did.\n\t *\n\t * @param range - 範圍字串 / Range string\n\t * @returns 比較器陣列 / Comparator array\n\t */\n\toverride parseRange(range: string)\n\t{\n\t\treturn parseRange(range, this.options)\n\t}\n\n\t/**\n\t * 從各種來源繼承範圍與選項\n\t * Inherit range and options from any supported source\n\t *\n\t * 輸入為原生 semver Range 時：合併兩側選項，且僅在選項完全相同的情況下\n\t * 直接沿用其 set；否則會重新解析（選項不同可能產生不同結果）。\n\t * When the input is a native semver Range: options from both sides are\n\t * merged, and its `set` is reused only when the merged options match\n\t * exactly — otherwise it is re-parsed, since differing options can produce\n\t * a different set.\n\t *\n\t * @param range - 範圍來源 / Range source\n\t * @param options - 已正規化的選項 / Normalized options\n\t * @returns 正規化後的 range、options 與（可能存在的）set / Normalized range, options, and (possibly) set\n\t */\n\tprotected _inherit(range: ISemverRangeInput, options: IOptions)\n\t{\n\t\tlet set: IComparatorSet;\n\n\t\tif (range instanceof semverRange)\n\t\t{\n\t\t\toptions = {\n\t\t\t\tloose: range.loose,\n\t\t\t\tincludePrerelease: range.includePrerelease,\n\t\t\t\t...range.options,\n\t\t\t\t...options,\n\t\t\t}\n\n\t\t\toptions = _normalizeOptions(options);\n\n\t\t\t// 選項一致才可安全搬移 set，否則可能與新選項不相符\n\t\t\t// The set may only be moved when options agree, otherwise it might\n\t\t\t// not match the new options\n\t\t\tif (_isSameOptions(range, options))\n\t\t\t{\n\t\t\t\tset = range.set;\n\t\t\t}\n\n\t\t\trange = range.raw;\n\t\t}\n\n\t\t/**\n\t\t * Comparator / SemVer 這兩種來源各自轉成可繼續解析的形態：\n\t\t * Comparator 直接包成單元素集合，SemVer 則取其格式化字串。\n\t\t * Comparator and SemVer sources are each converted into something\n\t\t * parseable: a Comparator becomes a single-element set, a SemVer is\n\t\t * reduced to its formatted string.\n\t\t */\n\t\tif (range instanceof Comparator)\n\t\t{\n\t\t\tset = [[range]];\n\t\t\trange = range.value\n\t\t}\n\t\telse if (range instanceof SemVer)\n\t\t{\n\t\t\trange = range.format();\n\t\t}\n\n\t\t// 有 set 但為空集合代表來源無效，提早拋錯避免帶到後續流程\n\t\t// An existing-but-empty set means the source is invalid; fail fast\n\t\t// instead of letting it travel further downstream\n\t\tif (set?.length === 0)\n\t\t{\n\t\t\tassertInvalidComparatorSet(set);\n\t\t}\n\n\t\toptions = _normalizeOptions(options);\n\n\t\t// 依選項決定是否把 & 視為「且」並整理空白\n\t\t// Decide per options whether `&` means \"AND\" and tidy the whitespace\n\t\trange = handleAmpersandAndSpaces(range, options);\n\n\t\treturn {\n\t\t\trange,\n\t\t\toptions,\n\t\t\tset,\n\t\t}\n\t}\n\n\t/**\n\t * 把選項同步到實例上\n\t * Sync options onto the instance\n\t *\n\t * options 寫入父層欄位後，再以 _copyOptions 複製 loose / includePrerelease\n\t * 兩個常用欄位，避免每次取值都要翻閱 options 物件。\n\t * After writing `options` to the parent field, `_copyOptions` mirrors the\n\t * frequently used `loose` / `includePrerelease` fields so readers do not\n\t * have to dig into the options object.\n\t *\n\t * @param options - 已正規化的選項 / Normalized options\n\t */\n\tprotected _inheritOptions(options: IOptions)\n\t{\n\t\t(this as any as semverRange).options = options;\n\t\t_copyOptions(this, options);\n\t}\n\n\t/**\n\t * 取得格式化後的範圍字串\n\t * Get the formatted range string\n\t *\n\t * 每次存取都從 set 重新組字串（而非取快取），因為 set 可能已被外部修改。\n\t * The string is rebuilt from `set` on every access instead of being cached,\n\t * because `set` may have been mutated externally.\n\t */\n\t// @ts-ignore\n\toverride get range()\n\t{\n\t\t// @ts-ignore\n\t\tthis.formatted = stringifyComparatorsSet(this.set);\n\t\treturn this.formatted\n\t}\n\n//\toverride format()\n//\t{\n//\t\treturn this.range\n//\t}\n\n\t/**\n\t * Return '*' instead of '' so that truthiness works.\n\t *\n\t * 回傳 `*` 而非空字串，可讓 `if (range.toRangeString())` 這類真值判斷成立。\n\t * Returning `*` instead of an empty string keeps truthiness checks such as\n\t * `if (range.toRangeString())` working.\n\t */\n\ttoRangeString()\n\t{\n\t\treturn toRangeString(this.range)\n\t}\n\n}\n\nexport { SemverRange as Range }\n\nexport default SemverRange\n"]}

package/lib/comparator/detect.d.ts

@@ -1,7 +1,21 @@
 import Comparator from 'semver/classes/comparator';
+/**
+ * 是否為 Null Set（<0.0.0-0，代表沒有任何版本符合）
+ * Whether it is a null set (<0.0.0-0, nothing can match)
+ *
+ * @param c - 比較器 / Comparator
+ * @returns 是否為 Null Set / Whether it is a null set
+ */
 export declare function isNullSet<T extends Comparator>(c: T): c is T & {
     value: '<0.0.0-0';
 };
+/**
+ * 是否為任意版本比較器（`*`，值為空字串）
+ * Whether it is an "any" comparator (`*`, empty-string value)
+ *
+ * @param c - 比較器 / Comparator
+ * @returns 是否為任意版本 / Whether it matches any version
+ */
 export declare function isAny<T extends Comparator>(c: T): c is T & {
     value: '';
 };

package/lib/comparator/detect.js

@@ -2,9 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNullSet = isNullSet;
 exports.isAny = isAny;
+/**
+ * 是否為 Null Set（<0.0.0-0，代表沒有任何版本符合）
+ * Whether it is a null set (<0.0.0-0, nothing can match)
+ *
+ * @param c - 比較器 / Comparator
+ * @returns 是否為 Null Set / Whether it is a null set
+ */
 function isNullSet(c) {
     return c.value === "<0.0.0-0" /* EnumSemverVersion.NULL */;
 }
+/**
+ * 是否為任意版本比較器（`*`，值為空字串）
+ * Whether it is an "any" comparator (`*`, empty-string value)
+ *
+ * @param c - 比較器 / Comparator
+ * @returns 是否為任意版本 / Whether it matches any version
+ */
 function isAny(c) {
     return c.value === "" /* EnumSemverVersion.ANY */;
 }

package/lib/comparator/detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect.js","sourceRoot":"","sources":["detect.ts"],"names":[],"mappings":";;AAGA,8BAKC;AAED,sBAKC;AAZD,SAAgB,SAAS,CAAuB,CAAI;IAInD,OAAO,CAAC,CAAC,KAAK,4CAA2B,CAAC;AAC3C,CAAC;AAED,SAAgB,KAAK,CAAuB,CAAI;IAI/C,OAAO,CAAC,CAAC,KAAK,mCAA0B,CAAC;AAC1C,CAAC","sourcesContent":["import Comparator from 'semver/classes/comparator';\nimport { EnumSemverVersion } from '../const';\n\nexport function isNullSet<T extends Comparator>(c: T): c is T & {\n\tvalue: '<0.0.0-0'\n}\n{\n\treturn c.value === EnumSemverVersion.NULL;\n}\n\nexport function isAny<T extends Comparator>(c: T): c is T & {\n\tvalue: ''\n}\n{\n\treturn c.value === EnumSemverVersion.ANY;\n}\n"]}
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["detect.ts"],"names":[],"mappings":";;AAUA,8BAKC;AASD,sBAKC;AA1BD;;;;;;GAMG;AACH,SAAgB,SAAS,CAAuB,CAAI;IAInD,OAAO,CAAC,CAAC,KAAK,4CAA2B,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,KAAK,CAAuB,CAAI;IAI/C,OAAO,CAAC,CAAC,KAAK,mCAA0B,CAAC;AAC1C,CAAC","sourcesContent":["import Comparator from 'semver/classes/comparator';\nimport { EnumSemverVersion } from '../const';\n\n/**\n * 是否為 Null Set（<0.0.0-0，代表沒有任何版本符合）\n * Whether it is a null set (<0.0.0-0, nothing can match)\n *\n * @param c - 比較器 / Comparator\n * @returns 是否為 Null Set / Whether it is a null set\n */\nexport function isNullSet<T extends Comparator>(c: T): c is T & {\n\tvalue: '<0.0.0-0'\n}\n{\n\treturn c.value === EnumSemverVersion.NULL;\n}\n\n/**\n * 是否為任意版本比較器（`*`，值為空字串）\n * Whether it is an \"any\" comparator (`*`, empty-string value)\n *\n * @param c - 比較器 / Comparator\n * @returns 是否為任意版本 / Whether it matches any version\n */\nexport function isAny<T extends Comparator>(c: T): c is T & {\n\tvalue: ''\n}\n{\n\treturn c.value === EnumSemverVersion.ANY;\n}\n"]}