@lazy-node/semver-ampersand 3.0.10 → 3.0.12

package/lib/range/normalizeRangeInput.js

@@ -6,6 +6,20 @@ const re_1 = require("semver/internal/re");
 const util_1 = require("./util");
 const debug_1 = tslib_1.__importDefault(require("semver/internal/debug"));
 const const_1 = require("../const");
+/**
+ * 把範圍字串正規化成後續可直接切割的形態
+ * Normalize a range string into a directly splittable form
+ *
+ * 這一層只處理「寫法」差異（hyphen、多餘空白、運算子後的空格），
+ * 不改變語意；先完成這些正規化，後續 parseComparator 才能假設輸入一致。
+ * This pass only fixes *spelling* differences (hyphen ranges, stray spaces,
+ * spaces after operators) without changing semantics; once it is done,
+ * parseComparator may assume a consistent input shape.
+ *
+ * @param range - 原始範圍字串 / Raw range string
+ * @param options - 解析選項（loose 決定正則、includePrerelease 影響 hyphen 上界）/ Parse options (loose picks the regex; includePrerelease affects the hyphen upper bound)
+ * @returns 正規化後的範圍字串 / Normalized range string
+ */
 function normalizeRangeInput(range, options) {
     // `1.2.3 - 1.2.4` => `>=1.2.3 <=1.2.4`
     const hr = options.loose ? re_1.re[re_1.t.HYPHENRANGELOOSE] : re_1.re[re_1.t.HYPHENRANGE];
@@ -19,6 +33,8 @@ function normalizeRangeInput(range, options) {
     // `^ 1.2.3` => `^1.2.3`
     range = range.replace(re_1.re[re_1.t.CARETTRIM], re_1.caretTrimReplace);
     // normalize spaces
+    // 最後統一收斂所有空白型別，讓 splitSpace 的切割結果可預期
+    // Collapse every whitespace flavour last so splitSpace cuts predictably
     range = range.replace(const_1.reSpaces, ' ');
     return range;
 }

package/lib/range/normalizeRangeInput.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalizeRangeInput.js","sourceRoot":"","sources":["normalizeRangeInput.ts"],"names":[],"mappings":";;AAMA,kDAoBC;;AAzBD,2CAAsG;AACtG,iCAAuC;AACvC,0EAA0C;AAC1C,oCAAoC;AAEpC,SAAgB,mBAAmB,CAAC,KAAa,EAAE,OAAiB;IAEnE,uCAAuC;IACvC,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAE,CAAC,MAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,OAAE,CAAC,MAAC,CAAC,WAAW,CAAC,CAAA;IACrE,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAA,oBAAa,EAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAA;IACnE,IAAA,eAAK,EAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;IAC9B,uCAAuC;IACvC,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAE,CAAC,MAAC,CAAC,cAAc,CAAC,EAAE,0BAAqB,CAAC,CAAA;IAClE,IAAA,eAAK,EAAC,iBAAiB,EAAE,KAAK,EAAE,OAAE,CAAC,MAAC,CAAC,cAAc,CAAC,CAAC,CAAA;IAErD,wBAAwB;IACxB,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAE,CAAC,MAAC,CAAC,SAAS,CAAC,EAAE,qBAAgB,CAAC,CAAA;IAExD,wBAAwB;IACxB,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAE,CAAC,MAAC,CAAC,SAAS,CAAC,EAAE,qBAAgB,CAAC,CAAA;IAExD,mBAAmB;IACnB,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,gBAAQ,EAAE,GAAG,CAAC,CAAA;IAEpC,OAAO,KAAK,CAAA;AACb,CAAC","sourcesContent":["import { IOptions } from '../types';\nimport { caretTrimReplace, comparatorTrimReplace, re, t, tildeTrimReplace } from 'semver/internal/re';\nimport { hyphenReplace } from './util';\nimport debug from 'semver/internal/debug';\nimport { reSpaces } from '../const';\n\nexport function normalizeRangeInput(range: string, options: IOptions)\n{\n\t// `1.2.3 - 1.2.4` => `>=1.2.3 <=1.2.4`\n\tconst hr = options.loose ? re[t.HYPHENRANGELOOSE] : re[t.HYPHENRANGE]\n\trange = range.replace(hr, hyphenReplace(options.includePrerelease))\n\tdebug('hyphen replace', range)\n\t// `> 1.2.3 < 1.2.5` => `>1.2.3 <1.2.5`\n\trange = range.replace(re[t.COMPARATORTRIM], comparatorTrimReplace)\n\tdebug('comparator trim', range, re[t.COMPARATORTRIM])\n\n\t// `~ 1.2.3` => `~1.2.3`\n\trange = range.replace(re[t.TILDETRIM], tildeTrimReplace)\n\n\t// `^ 1.2.3` => `^1.2.3`\n\trange = range.replace(re[t.CARETTRIM], caretTrimReplace)\n\n\t// normalize spaces\n\trange = range.replace(reSpaces, ' ')\n\n\treturn range\n}\n"]}
+{"version":3,"file":"normalizeRangeInput.js","sourceRoot":"","sources":["normalizeRangeInput.ts"],"names":[],"mappings":";;AAoBA,kDAsBC;;AAzCD,2CAAsG;AACtG,iCAAuC;AACvC,0EAA0C;AAC1C,oCAAoC;AAEpC;;;;;;;;;;;;;GAaG;AACH,SAAgB,mBAAmB,CAAC,KAAa,EAAE,OAAiB;IAEnE,uCAAuC;IACvC,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAE,CAAC,MAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,OAAE,CAAC,MAAC,CAAC,WAAW,CAAC,CAAA;IACrE,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAA,oBAAa,EAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAA;IACnE,IAAA,eAAK,EAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;IAC9B,uCAAuC;IACvC,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAE,CAAC,MAAC,CAAC,cAAc,CAAC,EAAE,0BAAqB,CAAC,CAAA;IAClE,IAAA,eAAK,EAAC,iBAAiB,EAAE,KAAK,EAAE,OAAE,CAAC,MAAC,CAAC,cAAc,CAAC,CAAC,CAAA;IAErD,wBAAwB;IACxB,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAE,CAAC,MAAC,CAAC,SAAS,CAAC,EAAE,qBAAgB,CAAC,CAAA;IAExD,wBAAwB;IACxB,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,OAAE,CAAC,MAAC,CAAC,SAAS,CAAC,EAAE,qBAAgB,CAAC,CAAA;IAExD,mBAAmB;IACnB,qCAAqC;IACrC,wEAAwE;IACxE,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,gBAAQ,EAAE,GAAG,CAAC,CAAA;IAEpC,OAAO,KAAK,CAAA;AACb,CAAC","sourcesContent":["import { IOptions } from '../types';\nimport { caretTrimReplace, comparatorTrimReplace, re, t, tildeTrimReplace } from 'semver/internal/re';\nimport { hyphenReplace } from './util';\nimport debug from 'semver/internal/debug';\nimport { reSpaces } from '../const';\n\n/**\n * 把範圍字串正規化成後續可直接切割的形態\n * Normalize a range string into a directly splittable form\n *\n * 這一層只處理「寫法」差異（hyphen、多餘空白、運算子後的空格），\n * 不改變語意；先完成這些正規化，後續 parseComparator 才能假設輸入一致。\n * This pass only fixes *spelling* differences (hyphen ranges, stray spaces,\n * spaces after operators) without changing semantics; once it is done,\n * parseComparator may assume a consistent input shape.\n *\n * @param range - 原始範圍字串 / Raw range string\n * @param options - 解析選項（loose 決定正則、includePrerelease 影響 hyphen 上界）/ Parse options (loose picks the regex; includePrerelease affects the hyphen upper bound)\n * @returns 正規化後的範圍字串 / Normalized range string\n */\nexport function normalizeRangeInput(range: string, options: IOptions)\n{\n\t// `1.2.3 - 1.2.4` => `>=1.2.3 <=1.2.4`\n\tconst hr = options.loose ? re[t.HYPHENRANGELOOSE] : re[t.HYPHENRANGE]\n\trange = range.replace(hr, hyphenReplace(options.includePrerelease))\n\tdebug('hyphen replace', range)\n\t// `> 1.2.3 < 1.2.5` => `>1.2.3 <1.2.5`\n\trange = range.replace(re[t.COMPARATORTRIM], comparatorTrimReplace)\n\tdebug('comparator trim', range, re[t.COMPARATORTRIM])\n\n\t// `~ 1.2.3` => `~1.2.3`\n\trange = range.replace(re[t.TILDETRIM], tildeTrimReplace)\n\n\t// `^ 1.2.3` => `^1.2.3`\n\trange = range.replace(re[t.CARETTRIM], caretTrimReplace)\n\n\t// normalize spaces\n\t// 最後統一收斂所有空白型別，讓 splitSpace 的切割結果可預期\n\t// Collapse every whitespace flavour last so splitSpace cuts predictably\n\trange = range.replace(reSpaces, ' ')\n\n\treturn range\n}\n"]}

package/lib/range/options.d.ts

@@ -1,4 +1,42 @@
 import { IOptions } from '../types';
+/**
+ * 比較兩組選項是否等價
+ * Check whether two option sets are equivalent
+ *
+ * 只比較 loose 與 includePrerelease 兩個「會影響解析結果」的欄位；
+ * 其餘欄位（如 noAmpersand）不參與，因為它們只影響前置字串處理。
+ * Only compares `loose` and `includePrerelease`, the fields that actually
+ * change parsing output; other fields (e.g. noAmpersand) are excluded because
+ * they only affect the earlier string-level handling.
+ *
+ * @param oldOptions - 原選項 / Original options
+ * @param newOptions - 新選項 / New options
+ * @returns 是否等價 / Whether they are equivalent
+ */
 export declare function _isSameOptions(oldOptions: IOptions, newOptions: IOptions): boolean;
+/**
+ * 把選項複製到目標物件
+ * Copy options into the target object
+ *
+ * 以 `!!` 強制布林，確保複製後的欄位一定是真正的 boolean。
+ * Coerced with `!!` so the copied fields are always real booleans.
+ *
+ * @param oldOptions - 目標選項（被就地修改）/ Target options (mutated in place)
+ * @param newOptions - 來源選項 / Source options
+ * @returns 同一個目標選項 / The same target options
+ */
 export declare function _copyOptions(oldOptions: IOptions, newOptions: IOptions): IOptions;
+/**
+ * 正規化選項中的布林欄位
+ * Normalize the boolean fields of the options
+ *
+ * 第三個參數傳 true（mode），連同未定義的欄位也一併補成 false，
+ * 讓 Range 實例上的 loose / includePrerelease 一定是布林值。
+ * The third argument (`mode`) is true so even undefined fields are materialized
+ * as false, guaranteeing `loose` / `includePrerelease` on a Range instance are
+ * always boolean.
+ *
+ * @param options - 選項物件（會被原地修改）/ Options object (mutated in place)
+ * @returns 正規化後的選項 / Normalized options
+ */
 export declare function _normalizeOptions(options: IOptions): IOptions;

package/lib/range/options.js

@@ -4,15 +4,53 @@ exports._isSameOptions = _isSameOptions;
 exports._copyOptions = _copyOptions;
 exports._normalizeOptions = _normalizeOptions;
 const fixBooleanProperty_1 = require("../util/fixBooleanProperty");
+/**
+ * 比較兩組選項是否等價
+ * Check whether two option sets are equivalent
+ *
+ * 只比較 loose 與 includePrerelease 兩個「會影響解析結果」的欄位；
+ * 其餘欄位（如 noAmpersand）不參與，因為它們只影響前置字串處理。
+ * Only compares `loose` and `includePrerelease`, the fields that actually
+ * change parsing output; other fields (e.g. noAmpersand) are excluded because
+ * they only affect the earlier string-level handling.
+ *
+ * @param oldOptions - 原選項 / Original options
+ * @param newOptions - 新選項 / New options
+ * @returns 是否等價 / Whether they are equivalent
+ */
 function _isSameOptions(oldOptions, newOptions) {
     return oldOptions.loose === newOptions.loose &&
         oldOptions.includePrerelease === newOptions.includePrerelease;
 }
+/**
+ * 把選項複製到目標物件
+ * Copy options into the target object
+ *
+ * 以 `!!` 強制布林，確保複製後的欄位一定是真正的 boolean。
+ * Coerced with `!!` so the copied fields are always real booleans.
+ *
+ * @param oldOptions - 目標選項（被就地修改）/ Target options (mutated in place)
+ * @param newOptions - 來源選項 / Source options
+ * @returns 同一個目標選項 / The same target options
+ */
 function _copyOptions(oldOptions, newOptions) {
     oldOptions.loose = !!newOptions.loose;
     oldOptions.includePrerelease = !!newOptions.includePrerelease;
     return oldOptions;
 }
+/**
+ * 正規化選項中的布林欄位
+ * Normalize the boolean fields of the options
+ *
+ * 第三個參數傳 true（mode），連同未定義的欄位也一併補成 false，
+ * 讓 Range 實例上的 loose / includePrerelease 一定是布林值。
+ * The third argument (`mode`) is true so even undefined fields are materialized
+ * as false, guaranteeing `loose` / `includePrerelease` on a Range instance are
+ * always boolean.
+ *
+ * @param options - 選項物件（會被原地修改）/ Options object (mutated in place)
+ * @returns 正規化後的選項 / Normalized options
+ */
 function _normalizeOptions(options) {
     options = (0, fixBooleanProperty_1.fixBooleanProperty)(options, [
         'loose',

package/lib/range/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["options.ts"],"names":[],"mappings":";;AAIA,wCAIC;AAED,oCAMC;AAED,8CAQC;AAxBD,mEAAsE;AAEtE,SAAgB,cAAc,CAAC,UAAoB,EAAE,UAAoB;IAExE,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK;QAC3C,UAAU,CAAC,iBAAiB,KAAK,UAAU,CAAC,iBAAiB,CAAA;AAC/D,CAAC;AAED,SAAgB,YAAY,CAAC,UAAoB,EAAE,UAAoB;IAEtE,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC,KAAK,CAAA;IACrC,UAAU,CAAC,iBAAiB,GAAG,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAA;IAE7D,OAAO,UAAU,CAAA;AAClB,CAAC;AAED,SAAgB,iBAAiB,CAAC,OAAiB;IAElD,OAAO,GAAG,IAAA,uCAAkB,EAAC,OAAO,EAAE;QACrC,OAAO;QACP,mBAAmB;KACnB,EAAE,IAAI,CAAC,CAAA;IAER,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["import semverRange from 'semver/classes/range';\nimport { IOptions } from '../types';\nimport { fixBooleanProperty, opts } from '../util/fixBooleanProperty';\n\nexport function _isSameOptions(oldOptions: IOptions, newOptions: IOptions)\n{\n\treturn oldOptions.loose === newOptions.loose &&\n\t\toldOptions.includePrerelease === newOptions.includePrerelease\n}\n\nexport function _copyOptions(oldOptions: IOptions, newOptions: IOptions)\n{\n\toldOptions.loose = !!newOptions.loose\n\toldOptions.includePrerelease = !!newOptions.includePrerelease\n\n\treturn oldOptions\n}\n\nexport function _normalizeOptions(options: IOptions)\n{\n\toptions = fixBooleanProperty(options, [\n\t\t'loose',\n\t\t'includePrerelease',\n\t], true)\n\n\treturn options\n}\n"]}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["options.ts"],"names":[],"mappings":";;AAkBA,wCAIC;AAaD,oCAMC;AAeD,8CAQC;AA9DD,mEAAsE;AAEtE;;;;;;;;;;;;;GAaG;AACH,SAAgB,cAAc,CAAC,UAAoB,EAAE,UAAoB;IAExE,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK;QAC3C,UAAU,CAAC,iBAAiB,KAAK,UAAU,CAAC,iBAAiB,CAAA;AAC/D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,YAAY,CAAC,UAAoB,EAAE,UAAoB;IAEtE,UAAU,CAAC,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC,KAAK,CAAA;IACrC,UAAU,CAAC,iBAAiB,GAAG,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAA;IAE7D,OAAO,UAAU,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,iBAAiB,CAAC,OAAiB;IAElD,OAAO,GAAG,IAAA,uCAAkB,EAAC,OAAO,EAAE;QACrC,OAAO;QACP,mBAAmB;KACnB,EAAE,IAAI,CAAC,CAAA;IAER,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["import semverRange from 'semver/classes/range';\nimport { IOptions } from '../types';\nimport { fixBooleanProperty, opts } from '../util/fixBooleanProperty';\n\n/**\n * 比較兩組選項是否等價\n * Check whether two option sets are equivalent\n *\n * 只比較 loose 與 includePrerelease 兩個「會影響解析結果」的欄位；\n * 其餘欄位（如 noAmpersand）不參與，因為它們只影響前置字串處理。\n * Only compares `loose` and `includePrerelease`, the fields that actually\n * change parsing output; other fields (e.g. noAmpersand) are excluded because\n * they only affect the earlier string-level handling.\n *\n * @param oldOptions - 原選項 / Original options\n * @param newOptions - 新選項 / New options\n * @returns 是否等價 / Whether they are equivalent\n */\nexport function _isSameOptions(oldOptions: IOptions, newOptions: IOptions)\n{\n\treturn oldOptions.loose === newOptions.loose &&\n\t\toldOptions.includePrerelease === newOptions.includePrerelease\n}\n\n/**\n * 把選項複製到目標物件\n * Copy options into the target object\n *\n * 以 `!!` 強制布林，確保複製後的欄位一定是真正的 boolean。\n * Coerced with `!!` so the copied fields are always real booleans.\n *\n * @param oldOptions - 目標選項（被就地修改）/ Target options (mutated in place)\n * @param newOptions - 來源選項 / Source options\n * @returns 同一個目標選項 / The same target options\n */\nexport function _copyOptions(oldOptions: IOptions, newOptions: IOptions)\n{\n\toldOptions.loose = !!newOptions.loose\n\toldOptions.includePrerelease = !!newOptions.includePrerelease\n\n\treturn oldOptions\n}\n\n/**\n * 正規化選項中的布林欄位\n * Normalize the boolean fields of the options\n *\n * 第三個參數傳 true（mode），連同未定義的欄位也一併補成 false，\n * 讓 Range 實例上的 loose / includePrerelease 一定是布林值。\n * The third argument (`mode`) is true so even undefined fields are materialized\n * as false, guaranteeing `loose` / `includePrerelease` on a Range instance are\n * always boolean.\n *\n * @param options - 選項物件（會被原地修改）/ Options object (mutated in place)\n * @returns 正規化後的選項 / Normalized options\n */\nexport function _normalizeOptions(options: IOptions)\n{\n\toptions = fixBooleanProperty(options, [\n\t\t'loose',\n\t\t'includePrerelease',\n\t], true)\n\n\treturn options\n}\n"]}

package/lib/range/parseRange.d.ts

@@ -1,20 +1,87 @@
 import { Comparator } from 'semver';
 import { IOptions } from '../types';
 /**
+ * 產生快取鍵所需的選項摘要
+ * Build the option summary used as part of the cache key
+ *
  * memoize range parsing for performance.
  * this is a very hot path, and fully deterministic.
+ *
+ * 只串接「有值」的選項（filter 已過濾掉 falsy），
+ * 讓不同選項組合產生不同鍵、相同組合則共用快取。
+ * Only truthy options are joined (the filter drops falsy ones), so distinct
+ * option combinations get distinct keys while identical ones share the cache.
+ *
+ * @param options - 解析選項 / Parse options
+ * @returns 快取鍵用的選項摘要 / Option summary for the cache key
  */
 export declare function getMemoOpts(options: IOptions): string;
+/**
+ * 把範圍展開成可逐段解析的比較器前驅字串
+ * Expand a range into comparator-ready strings before parsing
+ *
+ * 兩段式展開是必要的：第一段把 caret/tilde/xrange 等語法攤平，
+ * 攤平後可能產生重複或 `>=0.0.0` 這類等價寫法，第二段才負責去重與化簡。
+ * The two-pass expansion is required: the first pass flattens caret/tilde/
+ * xrange syntax, which may yield duplicates or equivalent spellings such as
+ * `>=0.0.0`; the second pass then deduplicates and simplifies.
+ *
+ * @param range - 已正規化的範圍字串 / Normalized range string
+ * @param options - 解析選項 / Parse options
+ * @returns 化簡後的比較器字串陣列 / Deduplicated comparator strings
+ */
 export declare function normalizeRangeInputForComparator(range: string, options: IOptions): string[];
+/**
+ * 解析範圍的核心流程（不含快取）
+ * Core range-parsing flow (without caching)
+ *
+ * @param range - 範圍字串 / Range string
+ * @param options - 解析選項 / Parse options
+ * @returns 不可變的比較器陣列 / Read-only array of comparators
+ */
 export declare function parseRangeCore(range: string, options: IOptions): ReadonlyArray<Comparator>;
 /**
+ * 過濾掉不符合比較器格式的項目
+ * Drop entries that do not match comparator syntax
+ *
  * in loose mode, throw out any that are not valid comparators
+ *
+ * @param rangeList - 比較器字串陣列 / Comparator strings
+ * @param options - 解析選項 / Parse options
+ * @returns 合法的比較器字串陣列 / Valid comparator strings
  */
 export declare function filterRangeListForComparator(rangeList: string[], options: IOptions): string[];
 /**
+ * 合併並化簡比較器清單
+ * Merge and simplify a comparator list
+ *
  * if any comparators are the null set, then replace with JUST null set
  * if more than one comparator, remove any * comparators
  * also, don't include the same comparator more than once
+ *
+ * 任意版本比較器 `*`（值為空字串）與其他比較器並存時會被移除，
+ * 因為 `* & >=1.0.0` 中的 `*` 不提供任何額外限制。
+ * When the "any" comparator `*` (empty-string value) coexists with others it
+ * is removed, since `*` in `* & >=1.0.0` adds no restriction.
+ *
+ * @param compList - 比較器陣列 / Comparator array
+ * @returns 化簡後的比較器陣列 / Simplified comparator array
  */
 export declare function reduceComparatorList(compList: Comparator[]): Comparator[];
+/**
+ * 解析範圍字串（含快取）
+ * Parse a range string (with caching)
+ *
+ * memoize range parsing for performance.
+ * this is a very hot path, and fully deterministic.
+ *
+ * 快取鍵包含選項摘要，因為同一段範圍在 loose / includePrerelease
+ * 不同設定下會解析出不同的比較器。
+ * The cache key includes the option summary: the same range parses into
+ * different comparators under loose / includePrerelease settings.
+ *
+ * @param range - 範圍字串 / Range string
+ * @param options - 解析選項 / Parse options
+ * @returns 不可變的比較器陣列 / Read-only array of comparators
+ */
 export declare function parseRange(range: string, options: IOptions): ReadonlyArray<Comparator>;

package/lib/range/parseRange.js

@@ -15,12 +15,37 @@ const split_1 = require("../util/split");
 const array_hyper_unique_1 = require("array-hyper-unique");
 const normalizeRangeInput_1 = require("./normalizeRangeInput");
 /**
+ * 產生快取鍵所需的選項摘要
+ * Build the option summary used as part of the cache key
+ *
  * memoize range parsing for performance.
  * this is a very hot path, and fully deterministic.
+ *
+ * 只串接「有值」的選項（filter 已過濾掉 falsy），
+ * 讓不同選項組合產生不同鍵、相同組合則共用快取。
+ * Only truthy options are joined (the filter drops falsy ones), so distinct
+ * option combinations get distinct keys while identical ones share the cache.
+ *
+ * @param options - 解析選項 / Parse options
+ * @returns 快取鍵用的選項摘要 / Option summary for the cache key
  */
 function getMemoOpts(options) {
     return Object.keys(options).filter(k => options[k]).join(',');
 }
+/**
+ * 把範圍展開成可逐段解析的比較器前驅字串
+ * Expand a range into comparator-ready strings before parsing
+ *
+ * 兩段式展開是必要的：第一段把 caret/tilde/xrange 等語法攤平，
+ * 攤平後可能產生重複或 `>=0.0.0` 這類等價寫法，第二段才負責去重與化簡。
+ * The two-pass expansion is required: the first pass flattens caret/tilde/
+ * xrange syntax, which may yield duplicates or equivalent spellings such as
+ * `>=0.0.0`; the second pass then deduplicates and simplifies.
+ *
+ * @param range - 已正規化的範圍字串 / Normalized range string
+ * @param options - 解析選項 / Parse options
+ * @returns 化簡後的比較器字串陣列 / Deduplicated comparator strings
+ */
 function normalizeRangeInputForComparator(range, options) {
     let rangeList = (0, split_1.splitSpace)(range)
         .map(comp => (0, util_1.parseComparator)(comp, options));
@@ -29,11 +54,25 @@ function normalizeRangeInputForComparator(range, options) {
         .map(comp => (0, util_1.replaceGTE0)(comp, options));
     return (0, array_hyper_unique_1.array_unique_overwrite)(rangeList);
 }
+/**
+ * 解析範圍的核心流程（不含快取）
+ * Core range-parsing flow (without caching)
+ *
+ * @param range - 範圍字串 / Range string
+ * @param options - 解析選項 / Parse options
+ * @returns 不可變的比較器陣列 / Read-only array of comparators
+ */
 function parseRangeCore(range, options) {
     range = (0, normalizeRangeInput_1.normalizeRangeInput)(range, options);
     // At this point, the range is completely trimmed and
     // ready to be split into comparators.
     let rangeList = normalizeRangeInputForComparator(range, options);
+    /**
+     * loose 模式才過濾：嚴格模式下無效比較器要讓建構失敗，
+     * 寬鬆模式則允許個別條件被忽略（與 semver 行為一致）。
+     * Filter only in loose mode: strict mode must fail on invalid comparators,
+     * while loose mode tolerates dropping them (same as semver).
+     */
     if (options.loose) {
         rangeList = filterRangeListForComparator(rangeList, options);
     }
@@ -43,32 +82,77 @@ function parseRangeCore(range, options) {
     return result;
 }
 /**
+ * 過濾掉不符合比較器格式的項目
+ * Drop entries that do not match comparator syntax
+ *
  * in loose mode, throw out any that are not valid comparators
+ *
+ * @param rangeList - 比較器字串陣列 / Comparator strings
+ * @param options - 解析選項 / Parse options
+ * @returns 合法的比較器字串陣列 / Valid comparator strings
  */
 function filterRangeListForComparator(rangeList, options) {
     const compRe = options.loose ? re_1.re[re_1.t.COMPARATORLOOSE] : re_1.re[re_1.t.COMPARATOR];
     return rangeList.filter(comp => !!comp.match(compRe));
 }
 /**
+ * 合併並化簡比較器清單
+ * Merge and simplify a comparator list
+ *
  * if any comparators are the null set, then replace with JUST null set
  * if more than one comparator, remove any * comparators
  * also, don't include the same comparator more than once
+ *
+ * 任意版本比較器 `*`（值為空字串）與其他比較器並存時會被移除，
+ * 因為 `* & >=1.0.0` 中的 `*` 不提供任何額外限制。
+ * When the "any" comparator `*` (empty-string value) coexists with others it
+ * is removed, since `*` in `* & >=1.0.0` adds no restriction.
+ *
+ * @param compList - 比較器陣列 / Comparator array
+ * @returns 化簡後的比較器陣列 / Simplified comparator array
  */
 function reduceComparatorList(compList) {
     const l = compList.length;
     const rangeMap = new Map();
     for (const comp of compList) {
+        /**
+         * Null Set（<0.0.0-0）代表「沒有任何版本符合」，
+         * 其餘條件再寬也無意義，直接短路回傳。
+         * A null set (<0.0.0-0) means "nothing matches"; no other condition
+         * can widen it, so short-circuit immediately.
+         */
         if ((0, detect_1.isNullSet)(comp)) {
             return [comp];
         }
         rangeMap.set(comp.value, comp);
     }
+    /**
+     * 只有一個以上比較器時才移除 `*`，避免把單純的 `*` 範圍清空。
+     * Drop `*` only when more than one comparator remains, so a plain `*`
+     * range is not emptied by accident.
+     */
     if (rangeMap.size > 1 && rangeMap.has('')) {
         rangeMap.delete('');
     }
     const result = [...rangeMap.values()];
     return result;
 }
+/**
+ * 解析範圍字串（含快取）
+ * Parse a range string (with caching)
+ *
+ * memoize range parsing for performance.
+ * this is a very hot path, and fully deterministic.
+ *
+ * 快取鍵包含選項摘要，因為同一段範圍在 loose / includePrerelease
+ * 不同設定下會解析出不同的比較器。
+ * The cache key includes the option summary: the same range parses into
+ * different comparators under loose / includePrerelease settings.
+ *
+ * @param range - 範圍字串 / Range string
+ * @param options - 解析選項 / Parse options
+ * @returns 不可變的比較器陣列 / Read-only array of comparators
+ */
 function parseRange(range, options) {
     range = range.trim();
     // memoize range parsing for performance.

package/lib/range/parseRange.js.map

@@ -1 +1 @@
-{"version":3,"file":"parseRange.js","sourceRoot":"","sources":["parseRange.ts"],"names":[],"mappings":"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","sourcesContent":["import { cache } from './cache';\nimport { Comparator } from 'semver';\nimport { isNullSet } from '../comparator/detect';\nimport { IOptions } from '../types';\nimport { re, t } from 'semver/internal/re'\nimport { parseComparator, replaceGTE0 } from './util';\nimport { splitSpace } from '../util/split';\nimport { array_unique_overwrite } from 'array-hyper-unique';\nimport { normalizeRangeInput } from './normalizeRangeInput';\n\n/**\n * memoize range parsing for performance.\n * this is a very hot path, and fully deterministic.\n */\nexport function getMemoOpts(options: IOptions)\n{\n\treturn Object.keys(options).filter(k => options[k]).join(',')\n}\n\nexport function normalizeRangeInputForComparator(range: string, options: IOptions)\n{\n\tlet rangeList = splitSpace(range)\n\t\t.map(comp => parseComparator(comp, options))\n\t;\n\n\trangeList = splitSpace(rangeList.join(' '))\n\t\t// >=0.0.0 is equivalent to *\n\t\t.map(comp => replaceGTE0(comp, options))\n\n\treturn array_unique_overwrite(rangeList)\n}\n\nexport function parseRangeCore(range: string, options: IOptions): ReadonlyArray<Comparator>\n{\n\trange = normalizeRangeInput(range, options);\n\n\t// At this point, the range is completely trimmed and\n\t// ready to be split into comparators.\n\n\tlet rangeList = normalizeRangeInputForComparator(range, options)\n\n\tif (options.loose)\n\t{\n\t\trangeList = filterRangeListForComparator(rangeList, options)\n\t}\n\n\tlet compList = rangeList\n\t\t.map(comp => new Comparator(comp, options))\n\n\tconst result = reduceComparatorList(compList)\n\n\treturn result\n}\n\n/**\n * in loose mode, throw out any that are not valid comparators\n */\nexport function filterRangeListForComparator(rangeList: string[], options: IOptions)\n{\n\tconst compRe = options.loose ? re[t.COMPARATORLOOSE] : re[t.COMPARATOR]\n\n\treturn rangeList.filter(comp => !!comp.match(compRe))\n}\n\n/**\n * if any comparators are the null set, then replace with JUST null set\n * if more than one comparator, remove any * comparators\n * also, don't include the same comparator more than once\n */\nexport function reduceComparatorList(compList: Comparator[])\n{\n\tconst l = compList.length\n\tconst rangeMap = new Map<string, Comparator>()\n\tfor (const comp of compList)\n\t{\n\t\tif (isNullSet(comp))\n\t\t{\n\t\t\treturn [comp]\n\t\t}\n\t\trangeMap.set(comp.value, comp)\n\t}\n\tif (rangeMap.size > 1 && rangeMap.has(''))\n\t{\n\t\trangeMap.delete('')\n\t}\n\n\tconst result = [...rangeMap.values()]\n\n\treturn result\n}\n\nexport function parseRange(range: string, options: IOptions): ReadonlyArray<Comparator>\n{\n\trange = range.trim()\n\n\t// memoize range parsing for performance.\n\t// this is a very hot path, and fully deterministic.\n\tconst memoOpts = getMemoOpts(options)\n\tconst memoKey = `parseRange:${memoOpts}:${range}`\n\tconst cached = cache.get(memoKey)\n\tif (cached)\n\t{\n\t\treturn cached\n\t}\n\n\tconst result = parseRangeCore(range, options)\n\n\tcache.set(memoKey, result)\n\treturn result\n}\n"]}
+{"version":3,"file":"parseRange.js","sourceRoot":"","sources":["parseRange.ts"],"names":[],"mappings":";;AAyBA,kCAGC;AAgBD,4EAWC;AAUD,wCA0BC;AAYD,oEAKC;AAkBD,oDA+BC;AAkBD,gCAkBC;AAjMD,mCAAgC;AAChC,mCAAoC;AACpC,iDAAiD;AAEjD,2CAA0C;AAC1C,iCAAsD;AACtD,yCAA2C;AAC3C,2DAA4D;AAC5D,+DAA4D;AAE5D;;;;;;;;;;;;;;GAcG;AACH,SAAgB,WAAW,CAAC,OAAiB;IAE5C,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,gCAAgC,CAAC,KAAa,EAAE,OAAiB;IAEhF,IAAI,SAAS,GAAG,IAAA,kBAAU,EAAC,KAAK,CAAC;SAC/B,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAA,sBAAe,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAC5C;IAED,SAAS,GAAG,IAAA,kBAAU,EAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1C,6BAA6B;SAC5B,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAA,kBAAW,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAEzC,OAAO,IAAA,2CAAsB,EAAC,SAAS,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,KAAa,EAAE,OAAiB;IAE9D,KAAK,GAAG,IAAA,yCAAmB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAE5C,qDAAqD;IACrD,sCAAsC;IAEtC,IAAI,SAAS,GAAG,gCAAgC,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IAEhE;;;;;OAKG;IACH,IAAI,OAAO,CAAC,KAAK,EACjB,CAAC;QACA,SAAS,GAAG,4BAA4B,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC7D,CAAC;IAED,IAAI,QAAQ,GAAG,SAAS;SACtB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,mBAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IAE5C,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAA;IAE7C,OAAO,MAAM,CAAA;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,4BAA4B,CAAC,SAAmB,EAAE,OAAiB;IAElF,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAE,CAAC,MAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,OAAE,CAAC,MAAC,CAAC,UAAU,CAAC,CAAA;IAEvE,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;AACtD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,oBAAoB,CAAC,QAAsB;IAE1D,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAA;IACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC9C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAC3B,CAAC;QACA;;;;;WAKG;QACH,IAAI,IAAA,kBAAS,EAAC,IAAI,CAAC,EACnB,CAAC;YACA,OAAO,CAAC,IAAI,CAAC,CAAA;QACd,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAC/B,CAAC;IACD;;;;OAIG;IACH,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EACzC,CAAC;QACA,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACpB,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAErC,OAAO,MAAM,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,UAAU,CAAC,KAAa,EAAE,OAAiB;IAE1D,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAEpB,yCAAyC;IACzC,oDAAoD;IACpD,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IACrC,MAAM,OAAO,GAAG,cAAc,QAAQ,IAAI,KAAK,EAAE,CAAA;IACjD,MAAM,MAAM,GAAG,aAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IACjC,IAAI,MAAM,EACV,CAAC;QACA,OAAO,MAAM,CAAA;IACd,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IAE7C,aAAK,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IAC1B,OAAO,MAAM,CAAA;AACd,CAAC","sourcesContent":["import { cache } from './cache';\nimport { Comparator } from 'semver';\nimport { isNullSet } from '../comparator/detect';\nimport { IOptions } from '../types';\nimport { re, t } from 'semver/internal/re'\nimport { parseComparator, replaceGTE0 } from './util';\nimport { splitSpace } from '../util/split';\nimport { array_unique_overwrite } from 'array-hyper-unique';\nimport { normalizeRangeInput } from './normalizeRangeInput';\n\n/**\n * 產生快取鍵所需的選項摘要\n * Build the option summary used as part of the cache key\n *\n * memoize range parsing for performance.\n * this is a very hot path, and fully deterministic.\n *\n * 只串接「有值」的選項（filter 已過濾掉 falsy），\n * 讓不同選項組合產生不同鍵、相同組合則共用快取。\n * Only truthy options are joined (the filter drops falsy ones), so distinct\n * option combinations get distinct keys while identical ones share the cache.\n *\n * @param options - 解析選項 / Parse options\n * @returns 快取鍵用的選項摘要 / Option summary for the cache key\n */\nexport function getMemoOpts(options: IOptions)\n{\n\treturn Object.keys(options).filter(k => options[k]).join(',')\n}\n\n/**\n * 把範圍展開成可逐段解析的比較器前驅字串\n * Expand a range into comparator-ready strings before parsing\n *\n * 兩段式展開是必要的：第一段把 caret/tilde/xrange 等語法攤平，\n * 攤平後可能產生重複或 `>=0.0.0` 這類等價寫法，第二段才負責去重與化簡。\n * The two-pass expansion is required: the first pass flattens caret/tilde/\n * xrange syntax, which may yield duplicates or equivalent spellings such as\n * `>=0.0.0`; the second pass then deduplicates and simplifies.\n *\n * @param range - 已正規化的範圍字串 / Normalized range string\n * @param options - 解析選項 / Parse options\n * @returns 化簡後的比較器字串陣列 / Deduplicated comparator strings\n */\nexport function normalizeRangeInputForComparator(range: string, options: IOptions)\n{\n\tlet rangeList = splitSpace(range)\n\t\t.map(comp => parseComparator(comp, options))\n\t;\n\n\trangeList = splitSpace(rangeList.join(' '))\n\t\t// >=0.0.0 is equivalent to *\n\t\t.map(comp => replaceGTE0(comp, options))\n\n\treturn array_unique_overwrite(rangeList)\n}\n\n/**\n * 解析範圍的核心流程（不含快取）\n * Core range-parsing flow (without caching)\n *\n * @param range - 範圍字串 / Range string\n * @param options - 解析選項 / Parse options\n * @returns 不可變的比較器陣列 / Read-only array of comparators\n */\nexport function parseRangeCore(range: string, options: IOptions): ReadonlyArray<Comparator>\n{\n\trange = normalizeRangeInput(range, options);\n\n\t// At this point, the range is completely trimmed and\n\t// ready to be split into comparators.\n\n\tlet rangeList = normalizeRangeInputForComparator(range, options)\n\n\t/**\n\t * loose 模式才過濾：嚴格模式下無效比較器要讓建構失敗，\n\t * 寬鬆模式則允許個別條件被忽略（與 semver 行為一致）。\n\t * Filter only in loose mode: strict mode must fail on invalid comparators,\n\t * while loose mode tolerates dropping them (same as semver).\n\t */\n\tif (options.loose)\n\t{\n\t\trangeList = filterRangeListForComparator(rangeList, options)\n\t}\n\n\tlet compList = rangeList\n\t\t.map(comp => new Comparator(comp, options))\n\n\tconst result = reduceComparatorList(compList)\n\n\treturn result\n}\n\n/**\n * 過濾掉不符合比較器格式的項目\n * Drop entries that do not match comparator syntax\n *\n * in loose mode, throw out any that are not valid comparators\n *\n * @param rangeList - 比較器字串陣列 / Comparator strings\n * @param options - 解析選項 / Parse options\n * @returns 合法的比較器字串陣列 / Valid comparator strings\n */\nexport function filterRangeListForComparator(rangeList: string[], options: IOptions)\n{\n\tconst compRe = options.loose ? re[t.COMPARATORLOOSE] : re[t.COMPARATOR]\n\n\treturn rangeList.filter(comp => !!comp.match(compRe))\n}\n\n/**\n * 合併並化簡比較器清單\n * Merge and simplify a comparator list\n *\n * if any comparators are the null set, then replace with JUST null set\n * if more than one comparator, remove any * comparators\n * also, don't include the same comparator more than once\n *\n * 任意版本比較器 `*`（值為空字串）與其他比較器並存時會被移除，\n * 因為 `* & >=1.0.0` 中的 `*` 不提供任何額外限制。\n * When the \"any\" comparator `*` (empty-string value) coexists with others it\n * is removed, since `*` in `* & >=1.0.0` adds no restriction.\n *\n * @param compList - 比較器陣列 / Comparator array\n * @returns 化簡後的比較器陣列 / Simplified comparator array\n */\nexport function reduceComparatorList(compList: Comparator[])\n{\n\tconst l = compList.length\n\tconst rangeMap = new Map<string, Comparator>()\n\tfor (const comp of compList)\n\t{\n\t\t/**\n\t\t * Null Set（<0.0.0-0）代表「沒有任何版本符合」，\n\t\t * 其餘條件再寬也無意義，直接短路回傳。\n\t\t * A null set (<0.0.0-0) means \"nothing matches\"; no other condition\n\t\t * can widen it, so short-circuit immediately.\n\t\t */\n\t\tif (isNullSet(comp))\n\t\t{\n\t\t\treturn [comp]\n\t\t}\n\t\trangeMap.set(comp.value, comp)\n\t}\n\t/**\n\t * 只有一個以上比較器時才移除 `*`，避免把單純的 `*` 範圍清空。\n\t * Drop `*` only when more than one comparator remains, so a plain `*`\n\t * range is not emptied by accident.\n\t */\n\tif (rangeMap.size > 1 && rangeMap.has(''))\n\t{\n\t\trangeMap.delete('')\n\t}\n\n\tconst result = [...rangeMap.values()]\n\n\treturn result\n}\n\n/**\n * 解析範圍字串（含快取）\n * Parse a range string (with caching)\n *\n * memoize range parsing for performance.\n * this is a very hot path, and fully deterministic.\n *\n * 快取鍵包含選項摘要，因為同一段範圍在 loose / includePrerelease\n * 不同設定下會解析出不同的比較器。\n * The cache key includes the option summary: the same range parses into\n * different comparators under loose / includePrerelease settings.\n *\n * @param range - 範圍字串 / Range string\n * @param options - 解析選項 / Parse options\n * @returns 不可變的比較器陣列 / Read-only array of comparators\n */\nexport function parseRange(range: string, options: IOptions): ReadonlyArray<Comparator>\n{\n\trange = range.trim()\n\n\t// memoize range parsing for performance.\n\t// this is a very hot path, and fully deterministic.\n\tconst memoOpts = getMemoOpts(options)\n\tconst memoKey = `parseRange:${memoOpts}:${range}`\n\tconst cached = cache.get(memoKey)\n\tif (cached)\n\t{\n\t\treturn cached\n\t}\n\n\tconst result = parseRangeCore(range, options)\n\n\tcache.set(memoKey, result)\n\treturn result\n}\n"]}

package/lib/range/stringifyRangeSet.d.ts

@@ -1,2 +1,14 @@
 import { buildRangeSet } from './buildRangeSet';
+/**
+ * 把二維條件集合組回範圍字串
+ * Join a two-dimensional condition set back into a range string
+ *
+ * 與 stringifyComparatorsSet 的差別在於輸入是「字串」的二維陣列
+ * （buildRangeSet 的輸出），而非 Comparator 物件。
+ * Unlike stringifyComparatorsSet, the input here is a two-dimensional array of
+ * *strings* (the output of buildRangeSet) rather than Comparator objects.
+ *
+ * @param rangeSet - 二維條件字串集合 / Two-dimensional condition sets
+ * @returns 範圍字串 / Range string
+ */
 export declare function stringifyRangeSet(rangeSet: ReturnType<typeof buildRangeSet>): string;

package/lib/range/stringifyRangeSet.js

@@ -2,6 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stringifyRangeSet = stringifyRangeSet;
 const const_1 = require("../const");
+/**
+ * 把二維條件集合組回範圍字串
+ * Join a two-dimensional condition set back into a range string
+ *
+ * 與 stringifyComparatorsSet 的差別在於輸入是「字串」的二維陣列
+ * （buildRangeSet 的輸出），而非 Comparator 物件。
+ * Unlike stringifyComparatorsSet, the input here is a two-dimensional array of
+ * *strings* (the output of buildRangeSet) rather than Comparator objects.
+ *
+ * @param rangeSet - 二維條件字串集合 / Two-dimensional condition sets
+ * @returns 範圍字串 / Range string
+ */
 function stringifyRangeSet(rangeSet) {
     return rangeSet
         .map(a => a.join(' '))

package/lib/range/stringifyRangeSet.js.map

@@ -1 +1 @@
-{"version":3,"file":"stringifyRangeSet.js","sourceRoot":"","sources":["stringifyRangeSet.ts"],"names":[],"mappings":";;AAGA,8CAKC;AAPD,oCAAsD;AAEtD,SAAgB,iBAAiB,CAAC,QAA0C;IAE3E,OAAO,QAAQ;SACb,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SACrB,IAAI,CAAC,kCAA0B,CAAC,CAAA;AACnC,CAAC","sourcesContent":["import { buildRangeSet } from './buildRangeSet';\nimport { separatorDoubleVerticalBar } from '../const';\n\nexport function stringifyRangeSet(rangeSet: ReturnType<typeof buildRangeSet>)\n{\n\treturn rangeSet\n\t\t.map(a => a.join(' '))\n\t\t.join(separatorDoubleVerticalBar)\n}\n"]}
+{"version":3,"file":"stringifyRangeSet.js","sourceRoot":"","sources":["stringifyRangeSet.ts"],"names":[],"mappings":";;AAeA,8CAKC;AAnBD,oCAAsD;AAEtD;;;;;;;;;;;GAWG;AACH,SAAgB,iBAAiB,CAAC,QAA0C;IAE3E,OAAO,QAAQ;SACb,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SACrB,IAAI,CAAC,kCAA0B,CAAC,CAAA;AACnC,CAAC","sourcesContent":["import { buildRangeSet } from './buildRangeSet';\nimport { separatorDoubleVerticalBar } from '../const';\n\n/**\n * 把二維條件集合組回範圍字串\n * Join a two-dimensional condition set back into a range string\n *\n * 與 stringifyComparatorsSet 的差別在於輸入是「字串」的二維陣列\n * （buildRangeSet 的輸出），而非 Comparator 物件。\n * Unlike stringifyComparatorsSet, the input here is a two-dimensional array of\n * *strings* (the output of buildRangeSet) rather than Comparator objects.\n *\n * @param rangeSet - 二維條件字串集合 / Two-dimensional condition sets\n * @returns 範圍字串 / Range string\n */\nexport function stringifyRangeSet(rangeSet: ReturnType<typeof buildRangeSet>)\n{\n\treturn rangeSet\n\t\t.map(a => a.join(' '))\n\t\t.join(separatorDoubleVerticalBar)\n}\n"]}

package/lib/range/toRangeString.d.ts

@@ -1 +1,13 @@
+/**
+ * 把範圍字串轉成永遠可用於真值判斷的形式
+ * Turn a range string into a form that is always truthy-testable
+ *
+ * 空字串代表「任意版本」，但空字串在 JavaScript 中是 falsy，
+ * 回傳 `*` 可讓 `if (range.toRangeString())` 的判斷保持直覺。
+ * An empty string means "any version" yet is falsy in JavaScript; returning
+ * `*` keeps `if (range.toRangeString())` intuitive.
+ *
+ * @param range - 範圍字串 / Range string
+ * @returns 原字串，空字串則回傳 `*` / The original string, or `*` when empty
+ */
 export declare function toRangeString(range: string): string | '*';

package/lib/range/toRangeString.js

@@ -1,6 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toRangeString = toRangeString;
+/**
+ * 把範圍字串轉成永遠可用於真值判斷的形式
+ * Turn a range string into a form that is always truthy-testable
+ *
+ * 空字串代表「任意版本」，但空字串在 JavaScript 中是 falsy，
+ * 回傳 `*` 可讓 `if (range.toRangeString())` 的判斷保持直覺。
+ * An empty string means "any version" yet is falsy in JavaScript; returning
+ * `*` keeps `if (range.toRangeString())` intuitive.
+ *
+ * @param range - 範圍字串 / Range string
+ * @returns 原字串，空字串則回傳 `*` / The original string, or `*` when empty
+ */
 function toRangeString(range) {
     return range || '*';
 }

package/lib/range/toRangeString.js.map

@@ -1 +1 @@
-{"version":3,"file":"toRangeString.js","sourceRoot":"","sources":["toRangeString.ts"],"names":[],"mappings":";;AACA,sCAGC;AAHD,SAAgB,aAAa,CAAC,KAAa;IAE1C,OAAO,KAAK,IAAI,GAAG,CAAA;AACpB,CAAC","sourcesContent":["\nexport function toRangeString(range: string): string | '*'\n{\n\treturn range || '*'\n}\n"]}
+{"version":3,"file":"toRangeString.js","sourceRoot":"","sources":["toRangeString.ts"],"names":[],"mappings":";;AAaA,sCAGC;AAfD;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAC,KAAa;IAE1C,OAAO,KAAK,IAAI,GAAG,CAAA;AACpB,CAAC","sourcesContent":["\n/**\n * 把範圍字串轉成永遠可用於真值判斷的形式\n * Turn a range string into a form that is always truthy-testable\n *\n * 空字串代表「任意版本」，但空字串在 JavaScript 中是 falsy，\n * 回傳 `*` 可讓 `if (range.toRangeString())` 的判斷保持直覺。\n * An empty string means \"any version\" yet is falsy in JavaScript; returning\n * `*` keeps `if (range.toRangeString())` intuitive.\n *\n * @param range - 範圍字串 / Range string\n * @returns 原字串，空字串則回傳 `*` / The original string, or `*` when empty\n */\nexport function toRangeString(range: string): string | '*'\n{\n\treturn range || '*'\n}\n"]}