@lazy-node/semver-ampersand 3.0.11 → 3.0.12

package/lib/const.d.ts

@@ -1,17 +1,55 @@
+/** 匹配任意空白序列（含換行、tab）/ Match any run of whitespace (incl. newline, tab) */
 export declare const reSpaces: RegExp;
+/**
+ * 匹配 ampersand 與空白的任意組合
+ * Match any combination of ampersand and whitespace
+ *
+ * 一次吃掉 `&&`、` & `、連續空白等寫法，替換成單一空白即完成「且」語意正規化。
+ * Consumes `&&`, ` & `, consecutive spaces, etc. in one shot; replacing with a
+ * single space normalizes the "AND" semantics.
+ */
 export declare const reAmpersandAndSpaces: RegExp;
+/**
+ * 檢查無效字元（不含 `&`）
+ * Detect invalid characters (`&` not allowed)
+ *
+ * 用於 noAmpersand: true 的路徑，此時 ampersand 視為無效字元。
+ * Used on the noAmpersand: true path, where ampersand counts as invalid.
+ */
 export declare const reInvalidCharacter: RegExp;
+/**
+ * 檢查無效字元（允許 `&`）
+ * Detect invalid characters (`&` allowed)
+ *
+ * 字元清單與 reInvalidCharacter 相同，只多了 `&`，
+ * 對應「預設啟用 ampersand 語法」的行為。
+ * Same character list as reInvalidCharacter plus `&`, matching the default
+ * behavior where ampersand syntax is enabled.
+ */
 export declare const reInvalidCharacterOrAmpersand: RegExp;
+/** 匹配 `||` 邏輯運算子（含兩側空白）/ Match the `||` operator (incl. surrounding whitespace) */
 export declare const reDoubleVerticalBar: RegExp;
+/** `||` 的輸出分隔字串（前後各一空白）/ Output separator for `||` (one space on each side) */
 export declare const separatorDoubleVerticalBar: " || ";
+/**
+ * 範圍展開時使用的特殊版本常數
+ * Special version constants used during range expansion
+ */
 export declare const enum EnumSemverVersion {
     /**
      * nothing is allowed
+     *
+     * Null Set：不允許任何版本（`>x` / `<x` 這類無意義條件的結果）
+     * Null Set: no version is allowed (result of meaningless conditions like `>x` / `<x`)
      */
     NULL = "<0.0.0-0",
     /**
      * nothing is forbidden
+     *
+     * 任意版本 `*`：沒有任何限制
+     * Any version `*`: no restriction at all
      */
     STAR = "*",
+    /** 空字串，等同任意版本 / Empty string, equivalent to any version */
     ANY = ""
 }

package/lib/const.js

@@ -1,22 +1,60 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnumSemverVersion = exports.separatorDoubleVerticalBar = exports.reDoubleVerticalBar = exports.reInvalidCharacterOrAmpersand = exports.reInvalidCharacter = exports.reAmpersandAndSpaces = exports.reSpaces = void 0;
+/** 匹配任意空白序列（含換行、tab）/ Match any run of whitespace (incl. newline, tab) */
 exports.reSpaces = /\s+/g;
+/**
+ * 匹配 ampersand 與空白的任意組合
+ * Match any combination of ampersand and whitespace
+ *
+ * 一次吃掉 `&&`、` & `、連續空白等寫法，替換成單一空白即完成「且」語意正規化。
+ * Consumes `&&`, ` & `, consecutive spaces, etc. in one shot; replacing with a
+ * single space normalizes the "AND" semantics.
+ */
 exports.reAmpersandAndSpaces = /[&\s]+/g;
+/**
+ * 檢查無效字元（不含 `&`）
+ * Detect invalid characters (`&` not allowed)
+ *
+ * 用於 noAmpersand: true 的路徑，此時 ampersand 視為無效字元。
+ * Used on the noAmpersand: true path, where ampersand counts as invalid.
+ */
 exports.reInvalidCharacter = /[^\s\w.*\-><~!^|=+]/;
+/**
+ * 檢查無效字元（允許 `&`）
+ * Detect invalid characters (`&` allowed)
+ *
+ * 字元清單與 reInvalidCharacter 相同，只多了 `&`，
+ * 對應「預設啟用 ampersand 語法」的行為。
+ * Same character list as reInvalidCharacter plus `&`, matching the default
+ * behavior where ampersand syntax is enabled.
+ */
 exports.reInvalidCharacterOrAmpersand = /[^\s\w.*\-><~!^|=+&]/;
+/** 匹配 `||` 邏輯運算子（含兩側空白）/ Match the `||` operator (incl. surrounding whitespace) */
 exports.reDoubleVerticalBar = /\s*\|\|\s*/g;
+/** `||` 的輸出分隔字串（前後各一空白）/ Output separator for `||` (one space on each side) */
 exports.separatorDoubleVerticalBar = ' || ';
+/**
+ * 範圍展開時使用的特殊版本常數
+ * Special version constants used during range expansion
+ */
 var EnumSemverVersion;
 (function (EnumSemverVersion) {
     /**
      * nothing is allowed
+     *
+     * Null Set：不允許任何版本（`>x` / `<x` 這類無意義條件的結果）
+     * Null Set: no version is allowed (result of meaningless conditions like `>x` / `<x`)
      */
     EnumSemverVersion["NULL"] = "<0.0.0-0";
     /**
      * nothing is forbidden
+     *
+     * 任意版本 `*`：沒有任何限制
+     * Any version `*`: no restriction at all
      */
     EnumSemverVersion["STAR"] = "*";
+    /** 空字串，等同任意版本 / Empty string, equivalent to any version */
     EnumSemverVersion["ANY"] = "";
 })(EnumSemverVersion || (exports.EnumSemverVersion = EnumSemverVersion = {}));
 //# sourceMappingURL=const.js.map

package/lib/const.js.map

@@ -1 +1 @@
-{"version":3,"file":"const.js","sourceRoot":"","sources":["const.ts"],"names":[],"mappings":";;;AACa,QAAA,QAAQ,GAAG,MAAM,CAAC;AAElB,QAAA,oBAAoB,GAAG,SAAS,CAAC;AAEjC,QAAA,kBAAkB,GAAG,qBAAqB,CAAC;AAE3C,QAAA,6BAA6B,GAAG,sBAAsB,CAAC;AAEvD,QAAA,mBAAmB,GAAG,aAAa,CAAC;AAEpC,QAAA,0BAA0B,GAAG,MAAe,CAAC;AAE1D,IAAkB,iBAWjB;AAXD,WAAkB,iBAAiB;IAElC;;OAEG;IACH,sCAAiB,CAAA;IACjB;;OAEG;IACH,+BAAU,CAAA;IACV,6BAAQ,CAAA;AACT,CAAC,EAXiB,iBAAiB,iCAAjB,iBAAiB,QAWlC","sourcesContent":["\nexport const reSpaces = /\\s+/g;\n\nexport const reAmpersandAndSpaces = /[&\\s]+/g;\n\nexport const reInvalidCharacter = /[^\\s\\w.*\\-><~!^|=+]/;\n\nexport const reInvalidCharacterOrAmpersand = /[^\\s\\w.*\\-><~!^|=+&]/;\n\nexport const reDoubleVerticalBar = /\\s*\\|\\|\\s*/g;\n\nexport const separatorDoubleVerticalBar = ' || ' as const;\n\nexport const enum EnumSemverVersion\n{\n\t/**\n\t * nothing is allowed\n\t */\n\tNULL = '<0.0.0-0',\n\t/**\n\t * nothing is forbidden\n\t */\n\tSTAR = '*',\n\tANY = '',\n}\n"]}
+{"version":3,"file":"const.js","sourceRoot":"","sources":["const.ts"],"names":[],"mappings":";;;AACA,0EAA0E;AAC7D,QAAA,QAAQ,GAAG,MAAM,CAAC;AAE/B;;;;;;;GAOG;AACU,QAAA,oBAAoB,GAAG,SAAS,CAAC;AAE9C;;;;;;GAMG;AACU,QAAA,kBAAkB,GAAG,qBAAqB,CAAC;AAExD;;;;;;;;GAQG;AACU,QAAA,6BAA6B,GAAG,sBAAsB,CAAC;AAEpE,mFAAmF;AACtE,QAAA,mBAAmB,GAAG,aAAa,CAAC;AAEjD,+EAA+E;AAClE,QAAA,0BAA0B,GAAG,MAAe,CAAC;AAE1D;;;GAGG;AACH,IAAkB,iBAkBjB;AAlBD,WAAkB,iBAAiB;IAElC;;;;;OAKG;IACH,sCAAiB,CAAA;IACjB;;;;;OAKG;IACH,+BAAU,CAAA;IACV,2DAA2D;IAC3D,6BAAQ,CAAA;AACT,CAAC,EAlBiB,iBAAiB,iCAAjB,iBAAiB,QAkBlC","sourcesContent":["\n/** 匹配任意空白序列（含換行、tab）/ Match any run of whitespace (incl. newline, tab) */\nexport const reSpaces = /\\s+/g;\n\n/**\n * 匹配 ampersand 與空白的任意組合\n * Match any combination of ampersand and whitespace\n *\n * 一次吃掉 `&&`、` & `、連續空白等寫法，替換成單一空白即完成「且」語意正規化。\n * Consumes `&&`, ` & `, consecutive spaces, etc. in one shot; replacing with a\n * single space normalizes the \"AND\" semantics.\n */\nexport const reAmpersandAndSpaces = /[&\\s]+/g;\n\n/**\n * 檢查無效字元（不含 `&`）\n * Detect invalid characters (`&` not allowed)\n *\n * 用於 noAmpersand: true 的路徑，此時 ampersand 視為無效字元。\n * Used on the noAmpersand: true path, where ampersand counts as invalid.\n */\nexport const reInvalidCharacter = /[^\\s\\w.*\\-><~!^|=+]/;\n\n/**\n * 檢查無效字元（允許 `&`）\n * Detect invalid characters (`&` allowed)\n *\n * 字元清單與 reInvalidCharacter 相同，只多了 `&`，\n * 對應「預設啟用 ampersand 語法」的行為。\n * Same character list as reInvalidCharacter plus `&`, matching the default\n * behavior where ampersand syntax is enabled.\n */\nexport const reInvalidCharacterOrAmpersand = /[^\\s\\w.*\\-><~!^|=+&]/;\n\n/** 匹配 `||` 邏輯運算子（含兩側空白）/ Match the `||` operator (incl. surrounding whitespace) */\nexport const reDoubleVerticalBar = /\\s*\\|\\|\\s*/g;\n\n/** `||` 的輸出分隔字串（前後各一空白）/ Output separator for `||` (one space on each side) */\nexport const separatorDoubleVerticalBar = ' || ' as const;\n\n/**\n * 範圍展開時使用的特殊版本常數\n * Special version constants used during range expansion\n */\nexport const enum EnumSemverVersion\n{\n\t/**\n\t * nothing is allowed\n\t *\n\t * Null Set：不允許任何版本（`>x` / `<x` 這類無意義條件的結果）\n\t * Null Set: no version is allowed (result of meaningless conditions like `>x` / `<x`)\n\t */\n\tNULL = '<0.0.0-0',\n\t/**\n\t * nothing is forbidden\n\t *\n\t * 任意版本 `*`：沒有任何限制\n\t * Any version `*`: no restriction at all\n\t */\n\tSTAR = '*',\n\t/** 空字串，等同任意版本 / Empty string, equivalent to any version */\n\tANY = '',\n}\n"]}

package/lib/handleAmpersandAndSpaces.d.ts

@@ -1,3 +1,19 @@
 import { IOptions } from './types';
+/**
+ * 把範圍字串中的 ampersand 與空白統一成單一空白
+ * Normalize ampersands and whitespace in a range string to a single space
+ *
+ * 未傳 noAmpersand 時使用 `[&\s]+`，可同時把 `a&&b`、`a & b` 這類寫法
+ * 收斂成 `a b`；一旦要求 noAmpersand，則只整理空白並保留 `&`，
+ * 讓後續的無效字元檢查能抓到它。
+ * Without `noAmpersand` the pattern `[&\s]+` collapses spellings such as
+ * `a&&b` and `a & b` into `a b` at once; when `noAmpersand` is requested only
+ * whitespace is normalized and `&` is kept, so the later invalid-character
+ * check can catch it.
+ *
+ * @param versionRange - 範圍字串或其他型別 / Range string or any other type
+ * @param options - 解析選項 / Parse options
+ * @returns 正規化後的範圍，非字串則原樣回傳 / Normalized range; non-strings are returned as-is
+ */
 export declare function handleAmpersandAndSpaces<T>(versionRange: T, options?: IOptions): T;
 export default handleAmpersandAndSpaces;

package/lib/handleAmpersandAndSpaces.js

@@ -2,6 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleAmpersandAndSpaces = handleAmpersandAndSpaces;
 const const_1 = require("./const");
+/**
+ * 把範圍字串中的 ampersand 與空白統一成單一空白
+ * Normalize ampersands and whitespace in a range string to a single space
+ *
+ * 未傳 noAmpersand 時使用 `[&\s]+`，可同時把 `a&&b`、`a & b` 這類寫法
+ * 收斂成 `a b`；一旦要求 noAmpersand，則只整理空白並保留 `&`，
+ * 讓後續的無效字元檢查能抓到它。
+ * Without `noAmpersand` the pattern `[&\s]+` collapses spellings such as
+ * `a&&b` and `a & b` into `a b` at once; when `noAmpersand` is requested only
+ * whitespace is normalized and `&` is kept, so the later invalid-character
+ * check can catch it.
+ *
+ * @param versionRange - 範圍字串或其他型別 / Range string or any other type
+ * @param options - 解析選項 / Parse options
+ * @returns 正規化後的範圍，非字串則原樣回傳 / Normalized range; non-strings are returned as-is
+ */
 function handleAmpersandAndSpaces(versionRange, options) {
     if (typeof versionRange === 'string') {
         return versionRange.replace((options === null || options === void 0 ? void 0 : options.noAmpersand) ? const_1.reSpaces : const_1.reAmpersandAndSpaces, ' ').trim();

package/lib/handleAmpersandAndSpaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"handleAmpersandAndSpaces.js","sourceRoot":"","sources":["handleAmpersandAndSpaces.ts"],"names":[],"mappings":";;AAGA,4DAQC;AAXD,mCAAyD;AAGzD,SAAgB,wBAAwB,CAAI,YAAe,EAAE,OAAkB;IAE9E,IAAI,OAAO,YAAY,KAAK,QAAQ,EACpC,CAAC;QACA,OAAO,YAAY,CAAC,OAAO,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,EAAC,CAAC,CAAC,gBAAQ,CAAC,CAAC,CAAC,4BAAoB,EAAE,GAAG,CAAC,CAAC,IAAI,EAAS,CAAA;IACvG,CAAC;IAED,OAAO,YAAY,CAAA;AACpB,CAAC;AAED,kBAAe,wBAAwB,CAAA","sourcesContent":["import { reAmpersandAndSpaces, reSpaces } from './const';\nimport { IOptions } from './types';\n\nexport function handleAmpersandAndSpaces<T>(versionRange: T, options?: IOptions): T\n{\n\tif (typeof versionRange === 'string')\n\t{\n\t\treturn versionRange.replace(options?.noAmpersand ? reSpaces : reAmpersandAndSpaces, ' ').trim() as any\n\t}\n\n\treturn versionRange\n}\n\nexport default handleAmpersandAndSpaces\n"]}
+{"version":3,"file":"handleAmpersandAndSpaces.js","sourceRoot":"","sources":["handleAmpersandAndSpaces.ts"],"names":[],"mappings":";;AAmBA,4DAQC;AA3BD,mCAAyD;AAGzD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,wBAAwB,CAAI,YAAe,EAAE,OAAkB;IAE9E,IAAI,OAAO,YAAY,KAAK,QAAQ,EACpC,CAAC;QACA,OAAO,YAAY,CAAC,OAAO,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,WAAW,EAAC,CAAC,CAAC,gBAAQ,CAAC,CAAC,CAAC,4BAAoB,EAAE,GAAG,CAAC,CAAC,IAAI,EAAS,CAAA;IACvG,CAAC;IAED,OAAO,YAAY,CAAA;AACpB,CAAC;AAED,kBAAe,wBAAwB,CAAA","sourcesContent":["import { reAmpersandAndSpaces, reSpaces } from './const';\nimport { IOptions } from './types';\n\n/**\n * 把範圍字串中的 ampersand 與空白統一成單一空白\n * Normalize ampersands and whitespace in a range string to a single space\n *\n * 未傳 noAmpersand 時使用 `[&\\s]+`，可同時把 `a&&b`、`a & b` 這類寫法\n * 收斂成 `a b`；一旦要求 noAmpersand，則只整理空白並保留 `&`，\n * 讓後續的無效字元檢查能抓到它。\n * Without `noAmpersand` the pattern `[&\\s]+` collapses spellings such as\n * `a&&b` and `a & b` into `a b` at once; when `noAmpersand` is requested only\n * whitespace is normalized and `&` is kept, so the later invalid-character\n * check can catch it.\n *\n * @param versionRange - 範圍字串或其他型別 / Range string or any other type\n * @param options - 解析選項 / Parse options\n * @returns 正規化後的範圍，非字串則原樣回傳 / Normalized range; non-strings are returned as-is\n */\nexport function handleAmpersandAndSpaces<T>(versionRange: T, options?: IOptions): T\n{\n\tif (typeof versionRange === 'string')\n\t{\n\t\treturn versionRange.replace(options?.noAmpersand ? reSpaces : reAmpersandAndSpaces, ' ').trim() as any\n\t}\n\n\treturn versionRange\n}\n\nexport default handleAmpersandAndSpaces\n"]}

package/lib/internal/parseOptionsOrLoose.d.ts

@@ -1,2 +1,22 @@
 import { IOptions, IOptionsOrLoose } from '../types';
+/**
+ * 把各種選項傳入形式統一成純物件
+ * Normalize the many ways options can be passed into a plain object
+ *
+ * 允許的傳入形式有三種，對應三個分支：
+ * 1. `false` → 明確的寬鬆旗標，轉成 { loose: false }
+ * 2. 非純物件（undefined、類陣列等）→ 給空物件，避免後續存取到意外欄位
+ * 3. 真正的布林值 `true` → 轉成 { loose: true }
+ * 其餘（純物件）則交給 fixBooleanProperty 把布林欄位正規化。
+ * Three input shapes map to the branches below:
+ * 1. `false` → an explicit loose flag, becoming { loose: false }
+ * 2. a non-plain object (undefined, array-like, …) → an empty object so
+ *    downstream code never reads unexpected fields
+ * 3. a real boolean `true` → { loose: true }
+ * Everything else (a plain object) goes through fixBooleanProperty to coerce
+ * its boolean fields.
+ *
+ * @param options - 任意形式的選項 / Options in any accepted form
+ * @returns 純物件形式的選項 / Options as a plain object
+ */
 export declare function parseOptionsOrLoose<T extends IOptions>(options: IOptionsOrLoose<T>): T;

package/lib/internal/parseOptionsOrLoose.js

@@ -3,6 +3,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseOptionsOrLoose = parseOptionsOrLoose;
 const index_1 = require("../util/index");
 const fixBooleanProperty_1 = require("../util/fixBooleanProperty");
+/**
+ * 把各種選項傳入形式統一成純物件
+ * Normalize the many ways options can be passed into a plain object
+ *
+ * 允許的傳入形式有三種，對應三個分支：
+ * 1. `false` → 明確的寬鬆旗標，轉成 { loose: false }
+ * 2. 非純物件（undefined、類陣列等）→ 給空物件，避免後續存取到意外欄位
+ * 3. 真正的布林值 `true` → 轉成 { loose: true }
+ * 其餘（純物件）則交給 fixBooleanProperty 把布林欄位正規化。
+ * Three input shapes map to the branches below:
+ * 1. `false` → an explicit loose flag, becoming { loose: false }
+ * 2. a non-plain object (undefined, array-like, …) → an empty object so
+ *    downstream code never reads unexpected fields
+ * 3. a real boolean `true` → { loose: true }
+ * Everything else (a plain object) goes through fixBooleanProperty to coerce
+ * its boolean fields.
+ *
+ * @param options - 任意形式的選項 / Options in any accepted form
+ * @returns 純物件形式的選項 / Options as a plain object
+ */
 function parseOptionsOrLoose(options) {
     if (options === false) {
         options = {

package/lib/internal/parseOptionsOrLoose.js.map

@@ -1 +1 @@
-{"version":3,"file":"parseOptionsOrLoose.js","sourceRoot":"","sources":["parseOptionsOrLoose.ts"],"names":[],"mappings":";;AAIA,kDAwBC;AA3BD,yCAA8C;AAC9C,mEAAsE;AAEtE,SAAgB,mBAAmB,CAAqB,OAA2B;IAElF,IAAI,OAAO,KAAK,KAAK,EACrB,CAAC;QACA,OAAO,GAAG;YACT,KAAK,EAAE,CAAC,CAAC,OAAO;SACX,CAAC;IACR,CAAC;SACI,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAA,qBAAa,EAAC,OAAO,CAAC,EAC3E,CAAC;QACA,OAAO,GAAG,EAAO,CAAC;IACnB,CAAC;SACI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAA,qBAAa,EAAC,OAAO,CAAC,EAC/D,CAAC;QACA,OAAO,GAAG;YACT,KAAK,EAAE,CAAC,CAAC,OAAO;SACX,CAAC;IACR,CAAC;SAED,CAAC;QACA,OAAO,GAAG,IAAA,uCAAkB,EAAC,OAAO,EAAE,yBAAI,CAAC,CAAA;IAC5C,CAAC;IAED,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["import { IOptions, IOptionsOrLoose } from '../types';\nimport { isPlainObject } from '../util/index';\nimport { fixBooleanProperty, opts } from '../util/fixBooleanProperty';\n\nexport function parseOptionsOrLoose<T extends IOptions>(options: IOptionsOrLoose<T>): T\n{\n\tif (options === false)\n\t{\n\t\toptions = {\n\t\t\tloose: !!options,\n\t\t} as T;\n\t}\n\telse if (!options || typeof options === 'object' && !isPlainObject(options))\n\t{\n\t\toptions = {} as T;\n\t}\n\telse if (typeof options !== 'object' || !isPlainObject(options))\n\t{\n\t\toptions = {\n\t\t\tloose: !!options,\n\t\t} as T;\n\t}\n\telse\n\t{\n\t\toptions = fixBooleanProperty(options, opts)\n\t}\n\n\treturn options\n}\n"]}
+{"version":3,"file":"parseOptionsOrLoose.js","sourceRoot":"","sources":["parseOptionsOrLoose.ts"],"names":[],"mappings":";;AAwBA,kDAwBC;AA/CD,yCAA8C;AAC9C,mEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,mBAAmB,CAAqB,OAA2B;IAElF,IAAI,OAAO,KAAK,KAAK,EACrB,CAAC;QACA,OAAO,GAAG;YACT,KAAK,EAAE,CAAC,CAAC,OAAO;SACX,CAAC;IACR,CAAC;SACI,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAA,qBAAa,EAAC,OAAO,CAAC,EAC3E,CAAC;QACA,OAAO,GAAG,EAAO,CAAC;IACnB,CAAC;SACI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAA,qBAAa,EAAC,OAAO,CAAC,EAC/D,CAAC;QACA,OAAO,GAAG;YACT,KAAK,EAAE,CAAC,CAAC,OAAO;SACX,CAAC;IACR,CAAC;SAED,CAAC;QACA,OAAO,GAAG,IAAA,uCAAkB,EAAC,OAAO,EAAE,yBAAI,CAAC,CAAA;IAC5C,CAAC;IAED,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["import { IOptions, IOptionsOrLoose } from '../types';\nimport { isPlainObject } from '../util/index';\nimport { fixBooleanProperty, opts } from '../util/fixBooleanProperty';\n\n/**\n * 把各種選項傳入形式統一成純物件\n * Normalize the many ways options can be passed into a plain object\n *\n * 允許的傳入形式有三種，對應三個分支：\n * 1. `false` → 明確的寬鬆旗標，轉成 { loose: false }\n * 2. 非純物件（undefined、類陣列等）→ 給空物件，避免後續存取到意外欄位\n * 3. 真正的布林值 `true` → 轉成 { loose: true }\n * 其餘（純物件）則交給 fixBooleanProperty 把布林欄位正規化。\n * Three input shapes map to the branches below:\n * 1. `false` → an explicit loose flag, becoming { loose: false }\n * 2. a non-plain object (undefined, array-like, …) → an empty object so\n *    downstream code never reads unexpected fields\n * 3. a real boolean `true` → { loose: true }\n * Everything else (a plain object) goes through fixBooleanProperty to coerce\n * its boolean fields.\n *\n * @param options - 任意形式的選項 / Options in any accepted form\n * @returns 純物件形式的選項 / Options as a plain object\n */\nexport function parseOptionsOrLoose<T extends IOptions>(options: IOptionsOrLoose<T>): T\n{\n\tif (options === false)\n\t{\n\t\toptions = {\n\t\t\tloose: !!options,\n\t\t} as T;\n\t}\n\telse if (!options || typeof options === 'object' && !isPlainObject(options))\n\t{\n\t\toptions = {} as T;\n\t}\n\telse if (typeof options !== 'object' || !isPlainObject(options))\n\t{\n\t\toptions = {\n\t\t\tloose: !!options,\n\t\t} as T;\n\t}\n\telse\n\t{\n\t\toptions = fixBooleanProperty(options, opts)\n\t}\n\n\treturn options\n}\n"]}

package/lib/maxSatisfying.d.ts

@@ -1,4 +1,19 @@
 import SemVer from 'semver/classes/semver';
 import { Options } from 'semver';
+/**
+ * 找出符合範圍的最大版本
+ * Find the largest version that satisfies the range
+ *
+ * 注意：此處呼叫 handleAmpersandAndSpaces 時不傳選項，
+ * 因此 `&` 一律會被視為「且」轉成空白，noAmpersand 在此路徑不生效。
+ * Note: handleAmpersandAndSpaces is called without options here, so `&` is
+ * always treated as "AND" (converted to a space); `noAmpersand` has no effect
+ * on this path.
+ *
+ * @param versions - 候選版本列表 / Candidate versions
+ * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 最大符合版本，找不到時為 null / Largest satisfying version, or null when none
+ */
 export declare function maxSatisfying<T extends string | SemVer>(versions: ReadonlyArray<T>, range: string | Range, optionsOrLoose?: boolean | Options): T;
 export default maxSatisfying;

package/lib/maxSatisfying.js

@@ -4,6 +4,21 @@ exports.maxSatisfying = maxSatisfying;
 const tslib_1 = require("tslib");
 const max_satisfying_1 = tslib_1.__importDefault(require("semver/ranges/max-satisfying"));
 const handleAmpersandAndSpaces_1 = require("./handleAmpersandAndSpaces");
+/**
+ * 找出符合範圍的最大版本
+ * Find the largest version that satisfies the range
+ *
+ * 注意：此處呼叫 handleAmpersandAndSpaces 時不傳選項，
+ * 因此 `&` 一律會被視為「且」轉成空白，noAmpersand 在此路徑不生效。
+ * Note: handleAmpersandAndSpaces is called without options here, so `&` is
+ * always treated as "AND" (converted to a space); `noAmpersand` has no effect
+ * on this path.
+ *
+ * @param versions - 候選版本列表 / Candidate versions
+ * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 最大符合版本，找不到時為 null / Largest satisfying version, or null when none
+ */
 function maxSatisfying(versions, range, optionsOrLoose) {
     return (0, max_satisfying_1.default)(versions, (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(range), optionsOrLoose);
 }

package/lib/maxSatisfying.js.map

@@ -1 +1 @@
-{"version":3,"file":"maxSatisfying.js","sourceRoot":"","sources":["maxSatisfying.ts"],"names":[],"mappings":";;AAKA,sCAMC;;AATD,0FAA+D;AAC/D,yEAAsE;AAEtE,SAAgB,aAAa,CAA4B,QAA0B,EAClF,KAAqB,EACrB,cAAkC;IAGlC,OAAO,IAAA,wBAAmB,EAAC,QAAQ,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,cAAc,CAAC,CAAA;AAC7F,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverMaxSatisfying from 'semver/ranges/max-satisfying';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\nexport function maxSatisfying<T extends string | SemVer>(versions: ReadonlyArray<T>,\n\trange: string | Range,\n\toptionsOrLoose?: boolean | Options,\n): T\n{\n\treturn semverMaxSatisfying(versions, handleAmpersandAndSpaces(range) as any, optionsOrLoose)\n}\n\nexport default maxSatisfying\n"]}
+{"version":3,"file":"maxSatisfying.js","sourceRoot":"","sources":["maxSatisfying.ts"],"names":[],"mappings":";;AAoBA,sCAMC;;AAxBD,0FAA+D;AAC/D,yEAAsE;AAEtE;;;;;;;;;;;;;;GAcG;AACH,SAAgB,aAAa,CAA4B,QAA0B,EAClF,KAAqB,EACrB,cAAkC;IAGlC,OAAO,IAAA,wBAAmB,EAAC,QAAQ,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,cAAc,CAAC,CAAA;AAC7F,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverMaxSatisfying from 'semver/ranges/max-satisfying';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\n/**\n * 找出符合範圍的最大版本\n * Find the largest version that satisfies the range\n *\n * 注意：此處呼叫 handleAmpersandAndSpaces 時不傳選項，\n * 因此 `&` 一律會被視為「且」轉成空白，noAmpersand 在此路徑不生效。\n * Note: handleAmpersandAndSpaces is called without options here, so `&` is\n * always treated as \"AND\" (converted to a space); `noAmpersand` has no effect\n * on this path.\n *\n * @param versions - 候選版本列表 / Candidate versions\n * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)\n * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n * @returns 最大符合版本，找不到時為 null / Largest satisfying version, or null when none\n */\nexport function maxSatisfying<T extends string | SemVer>(versions: ReadonlyArray<T>,\n\trange: string | Range,\n\toptionsOrLoose?: boolean | Options,\n): T\n{\n\treturn semverMaxSatisfying(versions, handleAmpersandAndSpaces(range) as any, optionsOrLoose)\n}\n\nexport default maxSatisfying\n"]}

package/lib/minSatisfying.d.ts

@@ -1,4 +1,19 @@
 import SemVer from 'semver/classes/semver';
 import { Options } from 'semver';
+/**
+ * 找出符合範圍的最小版本
+ * Find the smallest version that satisfies the range
+ *
+ * 注意：此處呼叫 handleAmpersandAndSpaces 時不傳選項，
+ * 因此 `&` 一律會被視為「且」轉成空白，noAmpersand 在此路徑不生效。
+ * Note: handleAmpersandAndSpaces is called without options here, so `&` is
+ * always treated as "AND" (converted to a space); `noAmpersand` has no effect
+ * on this path.
+ *
+ * @param versions - 候選版本列表 / Candidate versions
+ * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 最小符合版本，找不到時為 null / Smallest satisfying version, or null when none
+ */
 export declare function minSatisfying<T extends string | SemVer>(versions: ReadonlyArray<T>, range: string | Range, optionsOrLoose?: boolean | Options): T;
 export default minSatisfying;

package/lib/minSatisfying.js

@@ -4,6 +4,21 @@ exports.minSatisfying = minSatisfying;
 const tslib_1 = require("tslib");
 const min_satisfying_1 = tslib_1.__importDefault(require("semver/ranges/min-satisfying"));
 const handleAmpersandAndSpaces_1 = require("./handleAmpersandAndSpaces");
+/**
+ * 找出符合範圍的最小版本
+ * Find the smallest version that satisfies the range
+ *
+ * 注意：此處呼叫 handleAmpersandAndSpaces 時不傳選項，
+ * 因此 `&` 一律會被視為「且」轉成空白，noAmpersand 在此路徑不生效。
+ * Note: handleAmpersandAndSpaces is called without options here, so `&` is
+ * always treated as "AND" (converted to a space); `noAmpersand` has no effect
+ * on this path.
+ *
+ * @param versions - 候選版本列表 / Candidate versions
+ * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 最小符合版本，找不到時為 null / Smallest satisfying version, or null when none
+ */
 function minSatisfying(versions, range, optionsOrLoose) {
     return (0, min_satisfying_1.default)(versions, (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(range), optionsOrLoose);
 }

package/lib/minSatisfying.js.map

@@ -1 +1 @@
-{"version":3,"file":"minSatisfying.js","sourceRoot":"","sources":["minSatisfying.ts"],"names":[],"mappings":";;AAKA,sCAMC;;AATD,0FAA+D;AAC/D,yEAAsE;AAEtE,SAAgB,aAAa,CAA4B,QAA0B,EAClF,KAAqB,EACrB,cAAkC;IAGlC,OAAO,IAAA,wBAAmB,EAAC,QAAQ,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,cAAc,CAAC,CAAA;AAC7F,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverMinSatisfying from 'semver/ranges/min-satisfying';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\nexport function minSatisfying<T extends string | SemVer>(versions: ReadonlyArray<T>,\n\trange: string | Range,\n\toptionsOrLoose?: boolean | Options,\n): T\n{\n\treturn semverMinSatisfying(versions, handleAmpersandAndSpaces(range) as any, optionsOrLoose)\n}\n\nexport default minSatisfying\n"]}
+{"version":3,"file":"minSatisfying.js","sourceRoot":"","sources":["minSatisfying.ts"],"names":[],"mappings":";;AAoBA,sCAMC;;AAxBD,0FAA+D;AAC/D,yEAAsE;AAEtE;;;;;;;;;;;;;;GAcG;AACH,SAAgB,aAAa,CAA4B,QAA0B,EAClF,KAAqB,EACrB,cAAkC;IAGlC,OAAO,IAAA,wBAAmB,EAAC,QAAQ,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,cAAc,CAAC,CAAA;AAC7F,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverMinSatisfying from 'semver/ranges/min-satisfying';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\n/**\n * 找出符合範圍的最小版本\n * Find the smallest version that satisfies the range\n *\n * 注意：此處呼叫 handleAmpersandAndSpaces 時不傳選項，\n * 因此 `&` 一律會被視為「且」轉成空白，noAmpersand 在此路徑不生效。\n * Note: handleAmpersandAndSpaces is called without options here, so `&` is\n * always treated as \"AND\" (converted to a space); `noAmpersand` has no effect\n * on this path.\n *\n * @param versions - 候選版本列表 / Candidate versions\n * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)\n * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n * @returns 最小符合版本，找不到時為 null / Smallest satisfying version, or null when none\n */\nexport function minSatisfying<T extends string | SemVer>(versions: ReadonlyArray<T>,\n\trange: string | Range,\n\toptionsOrLoose?: boolean | Options,\n): T\n{\n\treturn semverMinSatisfying(versions, handleAmpersandAndSpaces(range) as any, optionsOrLoose)\n}\n\nexport default minSatisfying\n"]}

package/lib/range/buildRangeSet.d.ts

@@ -1,2 +1,15 @@
 import { IOptions } from '../types';
+/**
+ * 依 `||` 與空白把範圍切成二維的條件字串集合
+ * Split a range into a two-dimensional set of condition strings by `||` and spaces
+ *
+ * 先處理 ampersand（把 `&` 視為「且」），再切 `||`，
+ * 可確保 `a & b || c` 這類混合寫法被切成正確的三段。
+ * Ampersand handling (`&` = "AND") runs before splitting on `||`, so mixed
+ * input such as `a & b || c` is cut into the right three pieces.
+ *
+ * @param range - 範圍字串 / Range string
+ * @param options - 解析選項 / Parse options
+ * @returns 二維的條件字串集合（外層為 `||` 分隔）/ Two-dimensional condition sets (outer level = `||` groups)
+ */
 export declare function buildRangeSet(range: string, options?: IOptions): string[][];

package/lib/range/buildRangeSet.js

@@ -5,6 +5,19 @@ const split_1 = require("../util/split");
 const array_hyper_unique_1 = require("array-hyper-unique");
 const handleAmpersandAndSpaces_1 = require("../handleAmpersandAndSpaces");
 const normalizeRangeInput_1 = require("./normalizeRangeInput");
+/**
+ * 依 `||` 與空白把範圍切成二維的條件字串集合
+ * Split a range into a two-dimensional set of condition strings by `||` and spaces
+ *
+ * 先處理 ampersand（把 `&` 視為「且」），再切 `||`，
+ * 可確保 `a & b || c` 這類混合寫法被切成正確的三段。
+ * Ampersand handling (`&` = "AND") runs before splitting on `||`, so mixed
+ * input such as `a & b || c` is cut into the right three pieces.
+ *
+ * @param range - 範圍字串 / Range string
+ * @param options - 解析選項 / Parse options
+ * @returns 二維的條件字串集合（外層為 `||` 分隔）/ Two-dimensional condition sets (outer level = `||` groups)
+ */
 function buildRangeSet(range, options = {}) {
     range = (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(range, options);
     let rangeSet = (0, split_1.splitDoubleVerticalBar)(range)
@@ -13,6 +26,8 @@ function buildRangeSet(range, options = {}) {
         range = (0, normalizeRangeInput_1.normalizeRangeInput)(range, options);
         return (0, split_1.splitSpace)(range);
     });
+    // 去除重複的 `||` 分支，例如 `a || a` 只需保留一份
+    // Drop duplicated `||` branches, e.g. `a || a` only needs one copy
     rangeSet = (0, array_hyper_unique_1.array_unique_overwrite)(rangeSet);
     return rangeSet;
 }

package/lib/range/buildRangeSet.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildRangeSet.js","sourceRoot":"","sources":["buildRangeSet.ts"],"names":[],"mappings":";;AAMA,sCAiBC;AAtBD,yCAAmE;AACnE,2DAA4D;AAC5D,0EAAuE;AACvE,+DAA4D;AAE5D,SAAgB,aAAa,CAAC,KAAa,EAAE,UAAoB,EAAE;IAElE,KAAK,GAAG,IAAA,mDAAwB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAEjD,IAAI,QAAQ,GAAG,IAAA,8BAAsB,EAAC,KAAK,CAAC;QAC3C,6CAA6C;SAC5C,GAAG,CAAC,KAAK,CAAC,EAAE;QAEZ,KAAK,GAAG,IAAA,yCAAmB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAE5C,OAAO,IAAA,kBAAU,EAAC,KAAK,CAAC,CAAA;IACzB,CAAC,CAAC,CACF;IAED,QAAQ,GAAG,IAAA,2CAAsB,EAAC,QAAQ,CAAC,CAAA;IAE3C,OAAO,QAAQ,CAAA;AAChB,CAAC","sourcesContent":["import { IOptions } from '../types';\nimport { splitDoubleVerticalBar, splitSpace } from '../util/split';\nimport { array_unique_overwrite } from 'array-hyper-unique';\nimport { handleAmpersandAndSpaces } from '../handleAmpersandAndSpaces';\nimport { normalizeRangeInput } from './normalizeRangeInput';\n\nexport function buildRangeSet(range: string, options: IOptions = {})\n{\n\trange = handleAmpersandAndSpaces(range, options);\n\n\tlet rangeSet = splitDoubleVerticalBar(range)\n\t\t// map the range to a 2d array of comparators\n\t\t.map(range =>\n\t\t{\n\t\t\trange = normalizeRangeInput(range, options);\n\n\t\t\treturn splitSpace(range)\n\t\t})\n\t;\n\n\trangeSet = array_unique_overwrite(rangeSet)\n\n\treturn rangeSet\n}\n"]}
+{"version":3,"file":"buildRangeSet.js","sourceRoot":"","sources":["buildRangeSet.ts"],"names":[],"mappings":";;AAmBA,sCAmBC;AArCD,yCAAmE;AACnE,2DAA4D;AAC5D,0EAAuE;AACvE,+DAA4D;AAE5D;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAAC,KAAa,EAAE,UAAoB,EAAE;IAElE,KAAK,GAAG,IAAA,mDAAwB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAEjD,IAAI,QAAQ,GAAG,IAAA,8BAAsB,EAAC,KAAK,CAAC;QAC3C,6CAA6C;SAC5C,GAAG,CAAC,KAAK,CAAC,EAAE;QAEZ,KAAK,GAAG,IAAA,yCAAmB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAE5C,OAAO,IAAA,kBAAU,EAAC,KAAK,CAAC,CAAA;IACzB,CAAC,CAAC,CACF;IAED,mCAAmC;IACnC,mEAAmE;IACnE,QAAQ,GAAG,IAAA,2CAAsB,EAAC,QAAQ,CAAC,CAAA;IAE3C,OAAO,QAAQ,CAAA;AAChB,CAAC","sourcesContent":["import { IOptions } from '../types';\nimport { splitDoubleVerticalBar, splitSpace } from '../util/split';\nimport { array_unique_overwrite } from 'array-hyper-unique';\nimport { handleAmpersandAndSpaces } from '../handleAmpersandAndSpaces';\nimport { normalizeRangeInput } from './normalizeRangeInput';\n\n/**\n * 依 `||` 與空白把範圍切成二維的條件字串集合\n * Split a range into a two-dimensional set of condition strings by `||` and spaces\n *\n * 先處理 ampersand（把 `&` 視為「且」），再切 `||`，\n * 可確保 `a & b || c` 這類混合寫法被切成正確的三段。\n * Ampersand handling (`&` = \"AND\") runs before splitting on `||`, so mixed\n * input such as `a & b || c` is cut into the right three pieces.\n *\n * @param range - 範圍字串 / Range string\n * @param options - 解析選項 / Parse options\n * @returns 二維的條件字串集合（外層為 `||` 分隔）/ Two-dimensional condition sets (outer level = `||` groups)\n */\nexport function buildRangeSet(range: string, options: IOptions = {})\n{\n\trange = handleAmpersandAndSpaces(range, options);\n\n\tlet rangeSet = splitDoubleVerticalBar(range)\n\t\t// map the range to a 2d array of comparators\n\t\t.map(range =>\n\t\t{\n\t\t\trange = normalizeRangeInput(range, options);\n\n\t\t\treturn splitSpace(range)\n\t\t})\n\t;\n\n\t// 去除重複的 `||` 分支，例如 `a || a` 只需保留一份\n\t// Drop duplicated `||` branches, e.g. `a || a` only needs one copy\n\trangeSet = array_unique_overwrite(rangeSet)\n\n\treturn rangeSet\n}\n"]}

package/lib/range/cache.d.ts

@@ -1,3 +1,13 @@
 import { LRUCache } from 'lru-cache2';
 import { Comparator } from 'semver';
+/**
+ * 範圍解析結果的 LRU 快取
+ * LRU cache for range parsing results
+ *
+ * 以 1000 為上限，避免同一程序反覆解析不同範圍時無限成長；
+ * 鍵包含選項摘要，因此不同選項不會互相污染。
+ * Capped at 1000 so repeated parsing of varied ranges cannot grow without
+ * bound; the key embeds the option summary, so differing options never
+ * contaminate each other.
+ */
 export declare const cache: LRUCache<string, readonly Comparator[]>;

package/lib/range/cache.js

@@ -2,5 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cache = void 0;
 const lru_cache2_1 = require("lru-cache2");
+/**
+ * 範圍解析結果的 LRU 快取
+ * LRU cache for range parsing results
+ *
+ * 以 1000 為上限，避免同一程序反覆解析不同範圍時無限成長；
+ * 鍵包含選項摘要，因此不同選項不會互相污染。
+ * Capped at 1000 so repeated parsing of varied ranges cannot grow without
+ * bound; the key embeds the option summary, so differing options never
+ * contaminate each other.
+ */
 exports.cache = new lru_cache2_1.LRUCache({ max: 1000 });
 //# sourceMappingURL=cache.js.map

package/lib/range/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["cache.ts"],"names":[],"mappings":";;;AAAA,2CAAsC;AAGzB,QAAA,KAAK,GAAG,IAAI,qBAAQ,CAAoC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC","sourcesContent":["import { LRUCache } from 'lru-cache2';\nimport { Comparator } from 'semver';\n\nexport const cache = new LRUCache<string, ReadonlyArray<Comparator>>({ max: 1000 });\n"]}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["cache.ts"],"names":[],"mappings":";;;AAAA,2CAAsC;AAGtC;;;;;;;;;GASG;AACU,QAAA,KAAK,GAAG,IAAI,qBAAQ,CAAoC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC","sourcesContent":["import { LRUCache } from 'lru-cache2';\nimport { Comparator } from 'semver';\n\n/**\n * 範圍解析結果的 LRU 快取\n * LRU cache for range parsing results\n *\n * 以 1000 為上限，避免同一程序反覆解析不同範圍時無限成長；\n * 鍵包含選項摘要，因此不同選項不會互相污染。\n * Capped at 1000 so repeated parsing of varied ranges cannot grow without\n * bound; the key embeds the option summary, so differing options never\n * contaminate each other.\n */\nexport const cache = new LRUCache<string, ReadonlyArray<Comparator>>({ max: 1000 });\n"]}

package/lib/range/fixComparatorSet.d.ts

@@ -1,8 +1,58 @@
 import { IComparatorArrayInput, IComparatorSetInput } from '../types';
+/**
+ * 尋找是否存在任意版本比較器（`*`）
+ * Look for an "any" comparator (`*`)
+ *
+ * @param comparatorsArray - 比較器陣列 / Comparator array
+ * @returns 找到的比較器，否則 undefined / The comparator if found, otherwise undefined
+ */
 export declare function includeAny(comparatorsArray: IComparatorArrayInput): import("semver").Comparator;
 /**
+ * 若集合中含 `*`，整組範圍就等同於 `*`
+ * If the set contains `*`, the whole range is just `*`
+ *
  * if we have any that are `*`, then the range is just `*`
+ *
+ * unsafeOptimize 才會跨集合搜尋；預設只在「單一比較器正好是 `*`」時收斂，
+ * 因為跨集合的最佳化可能覆蓋掉 `||` 另一端有意義的條件。
+ * Cross-set searching only happens under unsafeOptimize; by default the set is
+ * collapsed only when a lone comparator is already `*`, because cross-set
+ * optimization could wipe out a meaningful condition on the other side of `||`.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled
+ * @returns 收斂後的集合 / The collapsed set
  */
 export declare function optimizeComparatorSetAny(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean): IComparatorSetInput;
+/**
+ * 移除 Null Set（<0.0.0-0）的集合
+ * Remove sets containing a null set (<0.0.0-0)
+ *
+ * unsafeOptimize 時只要集合內「任一」比較器是 null set 就整組移除；
+ * 否則只看第一個比較器，避免過度刪除（保留 semver 的保守行為）。
+ * With unsafeOptimize a set is dropped when *any* of its comparators is a null
+ * set; otherwise only the first comparator is inspected, keeping semver's
+ * conservative behavior and avoiding over-deletion.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled
+ * @returns 過濾後的集合 / Filtered set
+ */
 export declare function filterRemoveNullSet(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean): IComparatorArrayInput[];
+/**
+ * 修正並化簡整個比較器集合
+ * Fix and simplify the whole comparator set
+ *
+ * 順序很重要：先過濾 null set（同時保留一份首元素當保險），
+ * 再對剩餘集合做 `*` 收斂，最後清掉空陣列；
+ * 若全部被過濾掉，會回退到第一個集合，確保至少保留一個可判斷的條件。
+ * Order matters: null sets are filtered first (keeping the first element as a
+ * fallback), then `*` collapsing runs on the remainder, and finally empty
+ * arrays are dropped; if everything was filtered out, the original first set is
+ * restored so at least one condition remains judgeable.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled
+ * @returns 修正後的集合 / Fixed set
+ */
 export declare function fixComparatorSet(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean): IComparatorSetInput;

package/lib/range/fixComparatorSet.js

@@ -5,11 +5,31 @@ exports.optimizeComparatorSetAny = optimizeComparatorSetAny;
 exports.filterRemoveNullSet = filterRemoveNullSet;
 exports.fixComparatorSet = fixComparatorSet;
 const detect_1 = require("../comparator/detect");
+/**
+ * 尋找是否存在任意版本比較器（`*`）
+ * Look for an "any" comparator (`*`)
+ *
+ * @param comparatorsArray - 比較器陣列 / Comparator array
+ * @returns 找到的比較器，否則 undefined / The comparator if found, otherwise undefined
+ */
 function includeAny(comparatorsArray) {
     return comparatorsArray.find(c => (0, detect_1.isAny)(c));
 }
 /**
+ * 若集合中含 `*`，整組範圍就等同於 `*`
+ * If the set contains `*`, the whole range is just `*`
+ *
  * if we have any that are `*`, then the range is just `*`
+ *
+ * unsafeOptimize 才會跨集合搜尋；預設只在「單一比較器正好是 `*`」時收斂，
+ * 因為跨集合的最佳化可能覆蓋掉 `||` 另一端有意義的條件。
+ * Cross-set searching only happens under unsafeOptimize; by default the set is
+ * collapsed only when a lone comparator is already `*`, because cross-set
+ * optimization could wipe out a meaningful condition on the other side of `||`.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled
+ * @returns 收斂後的集合 / The collapsed set
  */
 function optimizeComparatorSetAny(comparatorsSet, unsafeOptimize) {
     unsafeOptimize = !!unsafeOptimize;
@@ -28,12 +48,42 @@ function optimizeComparatorSetAny(comparatorsSet, unsafeOptimize) {
     }
     return comparatorsSet;
 }
+/**
+ * 移除 Null Set（<0.0.0-0）的集合
+ * Remove sets containing a null set (<0.0.0-0)
+ *
+ * unsafeOptimize 時只要集合內「任一」比較器是 null set 就整組移除；
+ * 否則只看第一個比較器，避免過度刪除（保留 semver 的保守行為）。
+ * With unsafeOptimize a set is dropped when *any* of its comparators is a null
+ * set; otherwise only the first comparator is inspected, keeping semver's
+ * conservative behavior and avoiding over-deletion.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled
+ * @returns 過濾後的集合 / Filtered set
+ */
 function filterRemoveNullSet(comparatorsSet, unsafeOptimize) {
     if (unsafeOptimize) {
         return comparatorsSet.filter(ca => !ca.some(detect_1.isNullSet));
     }
     return comparatorsSet.filter(c => !(0, detect_1.isNullSet)(c[0]));
 }
+/**
+ * 修正並化簡整個比較器集合
+ * Fix and simplify the whole comparator set
+ *
+ * 順序很重要：先過濾 null set（同時保留一份首元素當保險），
+ * 再對剩餘集合做 `*` 收斂，最後清掉空陣列；
+ * 若全部被過濾掉，會回退到第一個集合，確保至少保留一個可判斷的條件。
+ * Order matters: null sets are filtered first (keeping the first element as a
+ * fallback), then `*` collapsing runs on the remainder, and finally empty
+ * arrays are dropped; if everything was filtered out, the original first set is
+ * restored so at least one condition remains judgeable.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled
+ * @returns 修正後的集合 / Fixed set
+ */
 function fixComparatorSet(comparatorsSet, unsafeOptimize) {
     unsafeOptimize = !!unsafeOptimize;
     // if we have any that are not the null set, throw out null sets.

package/lib/range/fixComparatorSet.js.map

@@ -1 +1 @@
-{"version":3,"file":"fixComparatorSet.js","sourceRoot":"","sources":["fixComparatorSet.ts"],"names":[],"mappings":";;AAGA,gCAGC;AAKD,4DAyBC;AAED,kDAQC;AAED,4CAwBC;AAvED,iDAAwD;AAExD,SAAgB,UAAU,CAAC,gBAAuC;IAEjE,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAA,cAAK,EAAC,CAAC,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED;;GAEG;AACH,SAAgB,wBAAwB,CAAC,cAAmC,EAAE,cAAwB;IAErG,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;IAElC,KAAK,MAAM,EAAE,IAAI,cAAc,EAC/B,CAAC;QACA,IAAI,cAAc,KAAK,IAAI,EAC3B,CAAC;YACA,IAAI,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;YAExB,IAAI,EAAE,EACN,CAAC;gBACA,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACxB,MAAM;YACP,CAAC;QACF,CAAC;QAED,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,IAAA,cAAK,EAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EACnC,CAAC;YACA,cAAc,GAAG,CAAC,EAAE,CAAC,CAAC;YACtB,MAAM;QACP,CAAC;IACF,CAAC;IAED,OAAO,cAAc,CAAA;AACtB,CAAC;AAED,SAAgB,mBAAmB,CAAC,cAAmC,EAAE,cAAwB;IAEhG,IAAI,cAAc,EAClB,CAAC;QACA,OAAO,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,kBAAS,CAAC,CAAC,CAAA;IACxD,CAAC;IAED,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAA,kBAAS,EAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACpD,CAAC;AAED,SAAgB,gBAAgB,CAAC,cAAmC,EAAE,cAAwB;IAE7F,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;IAElC,iEAAiE;IACjE,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAC7B,CAAC;QACA,oDAAoD;QACpD,MAAM,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QAChC,cAAc,GAAG,mBAAmB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QAErE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAC/B,CAAC;YACA,cAAc,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;aACI,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAClC,CAAC;YACA,cAAc,GAAG,wBAAwB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QAC3E,CAAC;IACF,CAAC;IAED,cAAc,GAAG,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAExD,OAAO,cAAc,CAAA;AACtB,CAAC","sourcesContent":["import { IComparatorArrayInput, IComparatorSetInput } from '../types';\nimport { isAny, isNullSet } from '../comparator/detect';\n\nexport function includeAny(comparatorsArray: IComparatorArrayInput)\n{\n\treturn comparatorsArray.find(c => isAny(c))\n}\n\n/**\n * if we have any that are `*`, then the range is just `*`\n */\nexport function optimizeComparatorSetAny(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean)\n{\n\tunsafeOptimize = !!unsafeOptimize;\n\n\tfor (const ca of comparatorsSet)\n\t{\n\t\tif (unsafeOptimize === true)\n\t\t{\n\t\t\tlet cc = includeAny(ca);\n\n\t\t\tif (cc)\n\t\t\t{\n\t\t\t\tcomparatorsSet = [[cc]];\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tif (ca.length === 1 && isAny(ca[0]))\n\t\t{\n\t\t\tcomparatorsSet = [ca];\n\t\t\tbreak;\n\t\t}\n\t}\n\n\treturn comparatorsSet\n}\n\nexport function filterRemoveNullSet(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean)\n{\n\tif (unsafeOptimize)\n\t{\n\t\treturn comparatorsSet.filter(ca => !ca.some(isNullSet))\n\t}\n\n\treturn comparatorsSet.filter(c => !isNullSet(c[0]))\n}\n\nexport function fixComparatorSet(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean)\n{\n\tunsafeOptimize = !!unsafeOptimize;\n\n\t// if we have any that are not the null set, throw out null sets.\n\tif (comparatorsSet.length > 1)\n\t{\n\t\t// keep the first one, in case they're all null sets\n\t\tconst first = comparatorsSet[0];\n\t\tcomparatorsSet = filterRemoveNullSet(comparatorsSet, unsafeOptimize);\n\n\t\tif (comparatorsSet.length === 0)\n\t\t{\n\t\t\tcomparatorsSet = [first];\n\t\t}\n\t\telse if (comparatorsSet.length > 1)\n\t\t{\n\t\t\tcomparatorsSet = optimizeComparatorSetAny(comparatorsSet, unsafeOptimize);\n\t\t}\n\t}\n\n\tcomparatorsSet = comparatorsSet.filter(ca => ca.length);\n\n\treturn comparatorsSet\n}\n"]}
+{"version":3,"file":"fixComparatorSet.js","sourceRoot":"","sources":["fixComparatorSet.ts"],"names":[],"mappings":";;AAUA,gCAGC;AAkBD,4DAyBC;AAgBD,kDAQC;AAkBD,4CAwBC;AAzHD,iDAAwD;AAExD;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,gBAAuC;IAEjE,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,IAAA,cAAK,EAAC,CAAC,CAAC,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,wBAAwB,CAAC,cAAmC,EAAE,cAAwB;IAErG,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;IAElC,KAAK,MAAM,EAAE,IAAI,cAAc,EAC/B,CAAC;QACA,IAAI,cAAc,KAAK,IAAI,EAC3B,CAAC;YACA,IAAI,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;YAExB,IAAI,EAAE,EACN,CAAC;gBACA,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACxB,MAAM;YACP,CAAC;QACF,CAAC;QAED,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,IAAA,cAAK,EAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EACnC,CAAC;YACA,cAAc,GAAG,CAAC,EAAE,CAAC,CAAC;YACtB,MAAM;QACP,CAAC;IACF,CAAC;IAED,OAAO,cAAc,CAAA;AACtB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,mBAAmB,CAAC,cAAmC,EAAE,cAAwB;IAEhG,IAAI,cAAc,EAClB,CAAC;QACA,OAAO,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,kBAAS,CAAC,CAAC,CAAA;IACxD,CAAC;IAED,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAA,kBAAS,EAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACpD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,gBAAgB,CAAC,cAAmC,EAAE,cAAwB;IAE7F,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;IAElC,iEAAiE;IACjE,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAC7B,CAAC;QACA,oDAAoD;QACpD,MAAM,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QAChC,cAAc,GAAG,mBAAmB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QAErE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAC/B,CAAC;YACA,cAAc,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;aACI,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAClC,CAAC;YACA,cAAc,GAAG,wBAAwB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QAC3E,CAAC;IACF,CAAC;IAED,cAAc,GAAG,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAExD,OAAO,cAAc,CAAA;AACtB,CAAC","sourcesContent":["import { IComparatorArrayInput, IComparatorSetInput } from '../types';\nimport { isAny, isNullSet } from '../comparator/detect';\n\n/**\n * 尋找是否存在任意版本比較器（`*`）\n * Look for an \"any\" comparator (`*`)\n *\n * @param comparatorsArray - 比較器陣列 / Comparator array\n * @returns 找到的比較器，否則 undefined / The comparator if found, otherwise undefined\n */\nexport function includeAny(comparatorsArray: IComparatorArrayInput)\n{\n\treturn comparatorsArray.find(c => isAny(c))\n}\n\n/**\n * 若集合中含 `*`，整組範圍就等同於 `*`\n * If the set contains `*`, the whole range is just `*`\n *\n * if we have any that are `*`, then the range is just `*`\n *\n * unsafeOptimize 才會跨集合搜尋；預設只在「單一比較器正好是 `*`」時收斂，\n * 因為跨集合的最佳化可能覆蓋掉 `||` 另一端有意義的條件。\n * Cross-set searching only happens under unsafeOptimize; by default the set is\n * collapsed only when a lone comparator is already `*`, because cross-set\n * optimization could wipe out a meaningful condition on the other side of `||`.\n *\n * @param comparatorsSet - 比較器集合 / Comparator set\n * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled\n * @returns 收斂後的集合 / The collapsed set\n */\nexport function optimizeComparatorSetAny(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean)\n{\n\tunsafeOptimize = !!unsafeOptimize;\n\n\tfor (const ca of comparatorsSet)\n\t{\n\t\tif (unsafeOptimize === true)\n\t\t{\n\t\t\tlet cc = includeAny(ca);\n\n\t\t\tif (cc)\n\t\t\t{\n\t\t\t\tcomparatorsSet = [[cc]];\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tif (ca.length === 1 && isAny(ca[0]))\n\t\t{\n\t\t\tcomparatorsSet = [ca];\n\t\t\tbreak;\n\t\t}\n\t}\n\n\treturn comparatorsSet\n}\n\n/**\n * 移除 Null Set（<0.0.0-0）的集合\n * Remove sets containing a null set (<0.0.0-0)\n *\n * unsafeOptimize 時只要集合內「任一」比較器是 null set 就整組移除；\n * 否則只看第一個比較器，避免過度刪除（保留 semver 的保守行為）。\n * With unsafeOptimize a set is dropped when *any* of its comparators is a null\n * set; otherwise only the first comparator is inspected, keeping semver's\n * conservative behavior and avoiding over-deletion.\n *\n * @param comparatorsSet - 比較器集合 / Comparator set\n * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled\n * @returns 過濾後的集合 / Filtered set\n */\nexport function filterRemoveNullSet(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean)\n{\n\tif (unsafeOptimize)\n\t{\n\t\treturn comparatorsSet.filter(ca => !ca.some(isNullSet))\n\t}\n\n\treturn comparatorsSet.filter(c => !isNullSet(c[0]))\n}\n\n/**\n * 修正並化簡整個比較器集合\n * Fix and simplify the whole comparator set\n *\n * 順序很重要：先過濾 null set（同時保留一份首元素當保險），\n * 再對剩餘集合做 `*` 收斂，最後清掉空陣列；\n * 若全部被過濾掉，會回退到第一個集合，確保至少保留一個可判斷的條件。\n * Order matters: null sets are filtered first (keeping the first element as a\n * fallback), then `*` collapsing runs on the remainder, and finally empty\n * arrays are dropped; if everything was filtered out, the original first set is\n * restored so at least one condition remains judgeable.\n *\n * @param comparatorsSet - 比較器集合 / Comparator set\n * @param unsafeOptimize - 是否啟用不安全最佳化 / Whether unsafe optimization is enabled\n * @returns 修正後的集合 / Fixed set\n */\nexport function fixComparatorSet(comparatorsSet: IComparatorSetInput, unsafeOptimize?: boolean)\n{\n\tunsafeOptimize = !!unsafeOptimize;\n\n\t// if we have any that are not the null set, throw out null sets.\n\tif (comparatorsSet.length > 1)\n\t{\n\t\t// keep the first one, in case they're all null sets\n\t\tconst first = comparatorsSet[0];\n\t\tcomparatorsSet = filterRemoveNullSet(comparatorsSet, unsafeOptimize);\n\n\t\tif (comparatorsSet.length === 0)\n\t\t{\n\t\t\tcomparatorsSet = [first];\n\t\t}\n\t\telse if (comparatorsSet.length > 1)\n\t\t{\n\t\t\tcomparatorsSet = optimizeComparatorSetAny(comparatorsSet, unsafeOptimize);\n\t\t}\n\t}\n\n\tcomparatorsSet = comparatorsSet.filter(ca => ca.length);\n\n\treturn comparatorsSet\n}\n"]}

package/lib/range/normalizeRangeInput.d.ts

@@ -1,2 +1,16 @@
 import { IOptions } from '../types';
+/**
+ * 把範圍字串正規化成後續可直接切割的形態
+ * 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
+ */
 export declare function normalizeRangeInput(range: string, options: IOptions): string;