@lazy-node/semver-ampersand 3.0.11 → 3.0.12

package/lib/satisfies.js

@@ -4,6 +4,23 @@ exports.satisfies = satisfies;
 const tslib_1 = require("tslib");
 const satisfies_1 = tslib_1.__importDefault(require("semver/functions/satisfies"));
 const handleAmpersandAndSpaces_1 = require("./handleAmpersandAndSpaces");
+/**
+ * 檢查版本是否符合範圍
+ * Check whether a version satisfies a range
+ *
+ * 先把 `&` 轉成空白（「且」語意）再交給原生 semver，因此 `>=1.0.0 & <2.0.0`
+ * 與 `>=1.0.0 <2.0.0` 等價；此處未轉傳選項給 handleAmpersandAndSpaces，
+ * 所以 `noAmpersand` 不生效，只有 loose / includePrerelease 會送到 semver。
+ * `&` is converted to a space ("AND") before delegating to native semver, so
+ * `>=1.0.0 & <2.0.0` equals `>=1.0.0 <2.0.0`; options are not forwarded to
+ * handleAmpersandAndSpaces, so `noAmpersand` is ignored here while loose /
+ * includePrerelease still reach semver.
+ *
+ * @param version - 要檢查的版本 / Version to check
+ * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 是否符合 / Whether it satisfies the range
+ */
 function satisfies(version, range, optionsOrLoose) {
     return (0, satisfies_1.default)(version, (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(range), optionsOrLoose);
 }

package/lib/satisfies.js.map

@@ -1 +1 @@
-{"version":3,"file":"satisfies.js","sourceRoot":"","sources":["satisfies.ts"],"names":[],"mappings":";;AAKA,8BAGC;;AAND,mFAAyD;AACzD,yEAAsE;AAEtE,SAAgB,SAAS,CAAC,OAAwB,EAAE,KAAqB,EAAE,cAAkC;IAE5G,OAAO,IAAA,mBAAe,EAAC,OAAO,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,cAAc,CAAC,CAAA;AACxF,CAAC;AAED,kBAAe,SAAS,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverSatisfies from 'semver/functions/satisfies';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\nexport function satisfies(version: string | SemVer, range: string | Range, optionsOrLoose?: boolean | Options)\n{\n\treturn semverSatisfies(version, handleAmpersandAndSpaces(range) as any, optionsOrLoose)\n}\n\nexport default satisfies\n"]}
+{"version":3,"file":"satisfies.js","sourceRoot":"","sources":["satisfies.ts"],"names":[],"mappings":";;AAsBA,8BAGC;;AAvBD,mFAAyD;AACzD,yEAAsE;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,SAAS,CAAC,OAAwB,EAAE,KAAqB,EAAE,cAAkC;IAE5G,OAAO,IAAA,mBAAe,EAAC,OAAO,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,cAAc,CAAC,CAAA;AACxF,CAAC;AAED,kBAAe,SAAS,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverSatisfies from 'semver/functions/satisfies';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\n/**\n * 檢查版本是否符合範圍\n * Check whether a version satisfies a range\n *\n * 先把 `&` 轉成空白（「且」語意）再交給原生 semver，因此 `>=1.0.0 & <2.0.0`\n * 與 `>=1.0.0 <2.0.0` 等價；此處未轉傳選項給 handleAmpersandAndSpaces，\n * 所以 `noAmpersand` 不生效，只有 loose / includePrerelease 會送到 semver。\n * `&` is converted to a space (\"AND\") before delegating to native semver, so\n * `>=1.0.0 & <2.0.0` equals `>=1.0.0 <2.0.0`; options are not forwarded to\n * handleAmpersandAndSpaces, so `noAmpersand` is ignored here while loose /\n * includePrerelease still reach semver.\n *\n * @param version - 要檢查的版本 / Version to check\n * @param range - 範圍字串（支援 `&`）/ Range string (`&` supported)\n * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n * @returns 是否符合 / Whether it satisfies the range\n */\nexport function satisfies(version: string | SemVer, range: string | Range, optionsOrLoose?: boolean | Options)\n{\n\treturn semverSatisfies(version, handleAmpersandAndSpaces(range) as any, optionsOrLoose)\n}\n\nexport default satisfies\n"]}

package/lib/simplifyRange.d.ts

@@ -1,4 +1,19 @@
 import SemVer from 'semver/classes/semver';
 import { Options } from 'semver';
+/**
+ * 在給定版本清單中簡化範圍
+ * Simplify a range against a given list of versions
+ *
+ * 先把 `&` 轉成空白再交給 semver，讓簡化結果與原生 semver 一致；
+ * 因為未傳選項，`noAmpersand` 在此路徑不生效。
+ * `&` is converted to a space before delegating to semver so the simplified
+ * result matches native semver; since options are not forwarded, `noAmpersand`
+ * has no effect on this path.
+ *
+ * @param ranges - 可用的版本清單 / Available version list
+ * @param range - 要簡化的範圍字串 / Range string to simplify
+ * @param options - semver 選項 / semver options
+ * @returns 簡化後的範圍字串 / Simplified range string
+ */
 export declare function simplifyRange<T extends string | SemVer>(ranges: string[], range: T, options?: Options): T;
 export default simplifyRange;

package/lib/simplifyRange.js

@@ -4,6 +4,21 @@ exports.simplifyRange = simplifyRange;
 const tslib_1 = require("tslib");
 const simplify_1 = tslib_1.__importDefault(require("semver/ranges/simplify"));
 const handleAmpersandAndSpaces_1 = require("./handleAmpersandAndSpaces");
+/**
+ * 在給定版本清單中簡化範圍
+ * Simplify a range against a given list of versions
+ *
+ * 先把 `&` 轉成空白再交給 semver，讓簡化結果與原生 semver 一致；
+ * 因為未傳選項，`noAmpersand` 在此路徑不生效。
+ * `&` is converted to a space before delegating to semver so the simplified
+ * result matches native semver; since options are not forwarded, `noAmpersand`
+ * has no effect on this path.
+ *
+ * @param ranges - 可用的版本清單 / Available version list
+ * @param range - 要簡化的範圍字串 / Range string to simplify
+ * @param options - semver 選項 / semver options
+ * @returns 簡化後的範圍字串 / Simplified range string
+ */
 function simplifyRange(ranges, range, options) {
     return (0, simplify_1.default)(ranges, (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(range), options);
 }

package/lib/simplifyRange.js.map

@@ -1 +1 @@
-{"version":3,"file":"simplifyRange.js","sourceRoot":"","sources":["simplifyRange.ts"],"names":[],"mappings":";;AAKA,sCAIC;;AAPD,8EAAyD;AACzD,yEAAsE;AAEtE,SAAgB,aAAa,CAA4B,MAAgB,EAAE,KAAQ,EAAE,OAAiB;IAGrG,OAAO,IAAA,kBAAmB,EAAC,MAAM,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,OAAO,CAAM,CAAA;AACzF,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverSimplifyRange from 'semver/ranges/simplify';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\nexport function simplifyRange<T extends string | SemVer>(ranges: string[], range: T, options?: Options,\n)\n{\n\treturn semverSimplifyRange(ranges, handleAmpersandAndSpaces(range) as any, options) as T\n}\n\nexport default simplifyRange\n"]}
+{"version":3,"file":"simplifyRange.js","sourceRoot":"","sources":["simplifyRange.ts"],"names":[],"mappings":";;AAoBA,sCAIC;;AAtBD,8EAAyD;AACzD,yEAAsE;AAEtE;;;;;;;;;;;;;;GAcG;AACH,SAAgB,aAAa,CAA4B,MAAgB,EAAE,KAAQ,EAAE,OAAiB;IAGrG,OAAO,IAAA,kBAAmB,EAAC,MAAM,EAAE,IAAA,mDAAwB,EAAC,KAAK,CAAQ,EAAE,OAAO,CAAM,CAAA;AACzF,CAAC;AAED,kBAAe,aAAa,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { Options } from 'semver';\nimport semverSimplifyRange from 'semver/ranges/simplify';\nimport { handleAmpersandAndSpaces } from './handleAmpersandAndSpaces';\n\n/**\n * 在給定版本清單中簡化範圍\n * Simplify a range against a given list of versions\n *\n * 先把 `&` 轉成空白再交給 semver，讓簡化結果與原生 semver 一致；\n * 因為未傳選項，`noAmpersand` 在此路徑不生效。\n * `&` is converted to a space before delegating to semver so the simplified\n * result matches native semver; since options are not forwarded, `noAmpersand`\n * has no effect on this path.\n *\n * @param ranges - 可用的版本清單 / Available version list\n * @param range - 要簡化的範圍字串 / Range string to simplify\n * @param options - semver 選項 / semver options\n * @returns 簡化後的範圍字串 / Simplified range string\n */\nexport function simplifyRange<T extends string | SemVer>(ranges: string[], range: T, options?: Options,\n)\n{\n\treturn semverSimplifyRange(ranges, handleAmpersandAndSpaces(range) as any, options) as T\n}\n\nexport default simplifyRange\n"]}

package/lib/types.d.ts

@@ -4,12 +4,42 @@ import SemVer from 'semver/classes/semver';
 import SemverRange from './Range';
 import { ITSArrayListMaybeReadonly } from 'ts-type/lib/type/base';
 import Comparator from 'semver/classes/comparator';
+/**
+ * 套件選項介面
+ * Package options interface
+ *
+ * 繼承 semver 的 Options 與 RangeOptions，再加上本套件特有的兩個開關。
+ * Extends semver's `Options` and `RangeOptions`, plus two switches unique to
+ * this package.
+ */
 export interface IOptions extends Options, RangeOptions {
+    /** 停用 ampersand (`&`) 支援，此時 `&` 會被當成無效字元 / Disable ampersand (`&`) support; `&` then counts as an invalid character */
     noAmpersand?: boolean;
+    /** 啟用不安全的比較器集合最佳化，可能改變邊界行為 / Enable unsafe comparator-set optimization; may alter edge behavior */
     unsafeOptimize?: boolean;
 }
+/**
+ * 選項或寬鬆旗標
+ * Options or loose flag
+ *
+ * 允許直接傳布林值作為 { loose } 的簡寫，與原生 semver 的呼叫習慣一致。
+ * Allows a boolean shorthand for `{ loose }`, matching native semver call
+ * conventions.
+ */
 export type IOptionsOrLoose<T extends Options = IOptions> = boolean | T;
+/** 比較器集合型別（沿用 semver Range 的 set）/ Comparator set type (mirrors semver Range's `set`) */
 export type IComparatorSet = Range["set"];
+/** 可為唯讀的比較器陣列 / Comparator array, possibly read-only */
 export type IComparatorArrayInput = ITSArrayListMaybeReadonly<Comparator>;
+/** 可為唯讀的比較器陣列之集合 / A set of comparator arrays, possibly read-only */
 export type IComparatorSetInput = ITSArrayListMaybeReadonly<IComparatorArrayInput>;
+/**
+ * 可接受的範圍輸入型別
+ * Accepted range input types
+ *
+ * 涵蓋字串、本套件的 Range、原生 Range、SemVer 與單一 Comparator，
+ * 對應 Range 建構函式 _inherit 中的各個分支。
+ * Covers a string, this package's Range, a native Range, a SemVer, and a
+ * single Comparator — one for each branch handled by Range's `_inherit`.
+ */
 export type ISemverRangeInput = string | SemverRange<any> | semverRange | SemVer | Comparator;

package/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["import { Options, Range, RangeOptions } from 'semver';\nimport semverRange from 'semver/classes/range';\nimport SemVer from 'semver/classes/semver';\nimport SemverRange from './Range';\nimport { ITSArrayListMaybeReadonly } from 'ts-type/lib/type/base';\nimport Comparator from 'semver/classes/comparator';\n\nexport interface IOptions extends Options, RangeOptions\n{\n\tnoAmpersand?: boolean,\n\tunsafeOptimize?: boolean,\n}\n\nexport type IOptionsOrLoose<T extends Options = IOptions> = boolean | T\n\nexport type IComparatorSet = Range[\"set\"];\n\nexport type IComparatorArrayInput = ITSArrayListMaybeReadonly<Comparator>;\n\nexport type IComparatorSetInput = ITSArrayListMaybeReadonly<IComparatorArrayInput>;\n\nexport type ISemverRangeInput = string | SemverRange<any> | semverRange | SemVer | Comparator;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["import { Options, Range, RangeOptions } from 'semver';\nimport semverRange from 'semver/classes/range';\nimport SemVer from 'semver/classes/semver';\nimport SemverRange from './Range';\nimport { ITSArrayListMaybeReadonly } from 'ts-type/lib/type/base';\nimport Comparator from 'semver/classes/comparator';\n\n/**\n * 套件選項介面\n * Package options interface\n *\n * 繼承 semver 的 Options 與 RangeOptions，再加上本套件特有的兩個開關。\n * Extends semver's `Options` and `RangeOptions`, plus two switches unique to\n * this package.\n */\nexport interface IOptions extends Options, RangeOptions\n{\n\t/** 停用 ampersand (`&`) 支援，此時 `&` 會被當成無效字元 / Disable ampersand (`&`) support; `&` then counts as an invalid character */\n\tnoAmpersand?: boolean,\n\n\t/** 啟用不安全的比較器集合最佳化，可能改變邊界行為 / Enable unsafe comparator-set optimization; may alter edge behavior */\n\tunsafeOptimize?: boolean,\n}\n\n/**\n * 選項或寬鬆旗標\n * Options or loose flag\n *\n * 允許直接傳布林值作為 { loose } 的簡寫，與原生 semver 的呼叫習慣一致。\n * Allows a boolean shorthand for `{ loose }`, matching native semver call\n * conventions.\n */\nexport type IOptionsOrLoose<T extends Options = IOptions> = boolean | T\n\n/** 比較器集合型別（沿用 semver Range 的 set）/ Comparator set type (mirrors semver Range's `set`) */\nexport type IComparatorSet = Range[\"set\"];\n\n/** 可為唯讀的比較器陣列 / Comparator array, possibly read-only */\nexport type IComparatorArrayInput = ITSArrayListMaybeReadonly<Comparator>;\n\n/** 可為唯讀的比較器陣列之集合 / A set of comparator arrays, possibly read-only */\nexport type IComparatorSetInput = ITSArrayListMaybeReadonly<IComparatorArrayInput>;\n\n/**\n * 可接受的範圍輸入型別\n * Accepted range input types\n *\n * 涵蓋字串、本套件的 Range、原生 Range、SemVer 與單一 Comparator，\n * 對應 Range 建構函式 _inherit 中的各個分支。\n * Covers a string, this package's Range, a native Range, a SemVer, and a\n * single Comparator — one for each branch handled by Range's `_inherit`.\n */\nexport type ISemverRangeInput = string | SemverRange<any> | semverRange | SemVer | Comparator;\n"]}

package/lib/util/array.d.ts

@@ -1 +1,15 @@
+/**
+ * 對二維陣列的「內層」逐一套用回呼
+ * Apply a callback to each inner array of a two-dimensional array
+ *
+ * 與單純的 map 差別在於 thisArg 會傳給內層的 map，
+ * 讓呼叫端能綁定方法所需的 this。
+ * Unlike a plain map, `thisArg` is forwarded to the inner maps so callers can
+ * bind the `this` a method expects.
+ *
+ * @param listSet - 二維陣列 / Two-dimensional array
+ * @param callbackFn - 內層回呼 / Callback applied to each inner array
+ * @param thisArg - 回呼的 this / `this` for the callback
+ * @returns 新的二維陣列 / A new two-dimensional array
+ */
 export declare function array_sub_map<U, T>(listSet: T[][], callbackFn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[][];

package/lib/util/array.js

@@ -1,6 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.array_sub_map = array_sub_map;
+/**
+ * 對二維陣列的「內層」逐一套用回呼
+ * Apply a callback to each inner array of a two-dimensional array
+ *
+ * 與單純的 map 差別在於 thisArg 會傳給內層的 map，
+ * 讓呼叫端能綁定方法所需的 this。
+ * Unlike a plain map, `thisArg` is forwarded to the inner maps so callers can
+ * bind the `this` a method expects.
+ *
+ * @param listSet - 二維陣列 / Two-dimensional array
+ * @param callbackFn - 內層回呼 / Callback applied to each inner array
+ * @param thisArg - 回呼的 this / `this` for the callback
+ * @returns 新的二維陣列 / A new two-dimensional array
+ */
 function array_sub_map(listSet, callbackFn, thisArg) {
     return listSet
         .map((list) => {

package/lib/util/array.js.map

@@ -1 +1 @@
-{"version":3,"file":"array.js","sourceRoot":"","sources":["array.ts"],"names":[],"mappings":";;AACA,sCAOC;AAPD,SAAgB,aAAa,CAAO,OAAc,EAAE,UAAsD,EAAE,OAAa;IAExH,OAAO,OAAO;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC,CAAC,CACF;AACF,CAAC","sourcesContent":["\nexport function array_sub_map<U, T>(listSet: T[][], callbackFn: (value: T, index: number, array: T[]) => U, thisArg?: any)\n{\n\treturn listSet\n\t\t.map((list) => {\n\t\t\treturn list.map(callbackFn, thisArg)\n\t\t})\n\t;\n}\n"]}
+{"version":3,"file":"array.js","sourceRoot":"","sources":["array.ts"],"names":[],"mappings":";;AAeA,sCAOC;AArBD;;;;;;;;;;;;;GAaG;AACH,SAAgB,aAAa,CAAO,OAAc,EAAE,UAAsD,EAAE,OAAa;IAExH,OAAO,OAAO;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IACrC,CAAC,CAAC,CACF;AACF,CAAC","sourcesContent":["\n/**\n * 對二維陣列的「內層」逐一套用回呼\n * Apply a callback to each inner array of a two-dimensional array\n *\n * 與單純的 map 差別在於 thisArg 會傳給內層的 map，\n * 讓呼叫端能綁定方法所需的 this。\n * Unlike a plain map, `thisArg` is forwarded to the inner maps so callers can\n * bind the `this` a method expects.\n *\n * @param listSet - 二維陣列 / Two-dimensional array\n * @param callbackFn - 內層回呼 / Callback applied to each inner array\n * @param thisArg - 回呼的 this / `this` for the callback\n * @returns 新的二維陣列 / A new two-dimensional array\n */\nexport function array_sub_map<U, T>(listSet: T[][], callbackFn: (value: T, index: number, array: T[]) => U, thisArg?: any)\n{\n\treturn listSet\n\t\t.map((list) => {\n\t\t\treturn list.map(callbackFn, thisArg)\n\t\t})\n\t;\n}\n"]}

package/lib/util/assert.d.ts

@@ -1,4 +1,46 @@
 import { IComparatorSetInput, IOptionsOrLoose } from '../types';
+/**
+ * 檢查字串是否含無效字元
+ * Check whether a string contains invalid characters
+ *
+ * 預設採用允許 `&` 的正則；要求 noAmpersand 時改用不允許 `&` 的正則，
+ * 讓 ampersand 語法可被明確關閉。
+ * By default the ampersand-tolerating regex is used; with noAmpersand the
+ * ampersand-disallowing one is used instead, so the syntax can be switched off
+ * explicitly.
+ *
+ * @param semver - 要檢查的字串 / String to check
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 是否含無效字元 / Whether it contains invalid characters
+ */
 export declare function hasInvalidCharacter(semver: string, optionsOrLoose?: IOptionsOrLoose): boolean;
+/**
+ * 斷言字串不含無效字元
+ * Assert that a string contains no invalid characters
+ *
+ * 與 hasInvalidCharacter 同樣依 noAmpersand 選擇正則；
+ * 例外訊息會帶出無效字元本身與其位置，方便除錯。
+ * Uses the same noAmpersand-driven regex selection as hasInvalidCharacter;
+ * the thrown message includes the offending character and its index to ease
+ * debugging.
+ *
+ * @param semver - 要檢查的字串 / String to check
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @throws {TypeError} 當字串含無效字元時 / When the string contains invalid characters
+ */
 export declare function assertInvalidCharacter(semver: string, optionsOrLoose?: IOptionsOrLoose): asserts semver is string;
+/**
+ * 斷言比較器集合不是空的
+ * Assert that a comparator set is not empty
+ *
+ * 空集合代表整個範圍無法解析成任何條件，
+ * 回傳的訊息可由呼叫端覆寫，以帶上原始範圍字串。
+ * An empty set means the whole range failed to parse into any condition; the
+ * message can be overridden by the caller so the original range string is
+ * included.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param message - 自訂錯誤訊息 / Custom error message
+ * @throws {TypeError} 當集合為空時 / When the set is empty
+ */
 export declare function assertInvalidComparatorSet(comparatorsSet: IComparatorSetInput, message?: string): asserts comparatorsSet is IComparatorSetInput;

package/lib/util/assert.js

@@ -5,11 +5,39 @@ exports.assertInvalidCharacter = assertInvalidCharacter;
 exports.assertInvalidComparatorSet = assertInvalidComparatorSet;
 const parseOptionsOrLoose_1 = require("../internal/parseOptionsOrLoose");
 const const_1 = require("../const");
+/**
+ * 檢查字串是否含無效字元
+ * Check whether a string contains invalid characters
+ *
+ * 預設採用允許 `&` 的正則；要求 noAmpersand 時改用不允許 `&` 的正則，
+ * 讓 ampersand 語法可被明確關閉。
+ * By default the ampersand-tolerating regex is used; with noAmpersand the
+ * ampersand-disallowing one is used instead, so the syntax can be switched off
+ * explicitly.
+ *
+ * @param semver - 要檢查的字串 / String to check
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 是否含無效字元 / Whether it contains invalid characters
+ */
 function hasInvalidCharacter(semver, optionsOrLoose) {
     return ((0, parseOptionsOrLoose_1.parseOptionsOrLoose)(optionsOrLoose).noAmpersand
         ? const_1.reInvalidCharacter
         : const_1.reInvalidCharacterOrAmpersand).test(semver);
 }
+/**
+ * 斷言字串不含無效字元
+ * Assert that a string contains no invalid characters
+ *
+ * 與 hasInvalidCharacter 同樣依 noAmpersand 選擇正則；
+ * 例外訊息會帶出無效字元本身與其位置，方便除錯。
+ * Uses the same noAmpersand-driven regex selection as hasInvalidCharacter;
+ * the thrown message includes the offending character and its index to ease
+ * debugging.
+ *
+ * @param semver - 要檢查的字串 / String to check
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @throws {TypeError} 當字串含無效字元時 / When the string contains invalid characters
+ */
 function assertInvalidCharacter(semver, optionsOrLoose) {
     const m = semver.match((0, parseOptionsOrLoose_1.parseOptionsOrLoose)(optionsOrLoose).noAmpersand
         ? const_1.reInvalidCharacter
@@ -18,6 +46,20 @@ function assertInvalidCharacter(semver, optionsOrLoose) {
         throw new TypeError(`Invalid SemVer Character: '${m[0]}' at index ${m.index} of '${semver}'`);
     }
 }
+/**
+ * 斷言比較器集合不是空的
+ * Assert that a comparator set is not empty
+ *
+ * 空集合代表整個範圍無法解析成任何條件，
+ * 回傳的訊息可由呼叫端覆寫，以帶上原始範圍字串。
+ * An empty set means the whole range failed to parse into any condition; the
+ * message can be overridden by the caller so the original range string is
+ * included.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @param message - 自訂錯誤訊息 / Custom error message
+ * @throws {TypeError} 當集合為空時 / When the set is empty
+ */
 function assertInvalidComparatorSet(comparatorsSet, message) {
     if (!(comparatorsSet === null || comparatorsSet === void 0 ? void 0 : comparatorsSet.length) || !Array.isArray(comparatorsSet)) {
         throw new TypeError(message !== null && message !== void 0 ? message : `Invalid ComparatorSet: ${comparatorsSet}`);

package/lib/util/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["assert.ts"],"names":[],"mappings":";;AAIA,kDAOC;AAED,wDAYC;AAED,gEAMC;AAhCD,yEAAsE;AACtE,oCAA6E;AAE7E,SAAgB,mBAAmB,CAAC,MAAc,EACjD,cAAgC;IAGhC,OAAO,CAAC,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAC,WAAW;QACtD,CAAC,CAAC,0BAAkB;QACpB,CAAC,CAAC,qCAA6B,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC;AAED,SAAgB,sBAAsB,CAAC,MAAc,EACpD,cAAgC;IAGhC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAC,WAAW;QACrE,CAAC,CAAC,0BAAkB;QACpB,CAAC,CAAC,qCAA6B,CAAC,CAAC;IAElC,IAAI,CAAC,aAAD,CAAC,uBAAD,CAAC,CAAE,MAAM,EACb,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,KAAK,QAAQ,MAAM,GAAG,CAAC,CAAA;IAC9F,CAAC;AACF,CAAC;AAED,SAAgB,0BAA0B,CAAC,cAAmC,EAAE,OAAgB;IAE/F,IAAI,CAAC,CAAA,cAAc,aAAd,cAAc,uBAAd,cAAc,CAAE,MAAM,CAAA,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAC7D,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,0BAA0B,cAAc,EAAE,CAAC,CAAA;IAC3E,CAAC;AACF,CAAC","sourcesContent":["import { IComparatorSetInput, IOptionsOrLoose } from '../types';\nimport { parseOptionsOrLoose } from '../internal/parseOptionsOrLoose';\nimport { reInvalidCharacter, reInvalidCharacterOrAmpersand } from '../const';\n\nexport function hasInvalidCharacter(semver: string,\n\toptionsOrLoose?: IOptionsOrLoose,\n)\n{\n\treturn (parseOptionsOrLoose(optionsOrLoose).noAmpersand\n\t\t? reInvalidCharacter\n\t\t: reInvalidCharacterOrAmpersand).test(semver)\n}\n\nexport function assertInvalidCharacter(semver: string,\n\toptionsOrLoose?: IOptionsOrLoose,\n): asserts semver is string\n{\n\tconst m = semver.match(parseOptionsOrLoose(optionsOrLoose).noAmpersand\n\t\t? reInvalidCharacter\n\t\t: reInvalidCharacterOrAmpersand);\n\n\tif (m?.length)\n\t{\n\t\tthrow new TypeError(`Invalid SemVer Character: '${m[0]}' at index ${m.index} of '${semver}'`)\n\t}\n}\n\nexport function assertInvalidComparatorSet(comparatorsSet: IComparatorSetInput, message?: string): asserts comparatorsSet is IComparatorSetInput\n{\n\tif (!comparatorsSet?.length || !Array.isArray(comparatorsSet))\n\t{\n\t\tthrow new TypeError(message ?? `Invalid ComparatorSet: ${comparatorsSet}`)\n\t}\n}\n"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["assert.ts"],"names":[],"mappings":";;AAkBA,kDAOC;AAgBD,wDAYC;AAgBD,gEAMC;AA1ED,yEAAsE;AACtE,oCAA6E;AAE7E;;;;;;;;;;;;;GAaG;AACH,SAAgB,mBAAmB,CAAC,MAAc,EACjD,cAAgC;IAGhC,OAAO,CAAC,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAC,WAAW;QACtD,CAAC,CAAC,0BAAkB;QACpB,CAAC,CAAC,qCAA6B,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,sBAAsB,CAAC,MAAc,EACpD,cAAgC;IAGhC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAC,WAAW;QACrE,CAAC,CAAC,0BAAkB;QACpB,CAAC,CAAC,qCAA6B,CAAC,CAAC;IAElC,IAAI,CAAC,aAAD,CAAC,uBAAD,CAAC,CAAE,MAAM,EACb,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,KAAK,QAAQ,MAAM,GAAG,CAAC,CAAA;IAC9F,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,0BAA0B,CAAC,cAAmC,EAAE,OAAgB;IAE/F,IAAI,CAAC,CAAA,cAAc,aAAd,cAAc,uBAAd,cAAc,CAAE,MAAM,CAAA,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAC7D,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,0BAA0B,cAAc,EAAE,CAAC,CAAA;IAC3E,CAAC;AACF,CAAC","sourcesContent":["import { IComparatorSetInput, IOptionsOrLoose } from '../types';\nimport { parseOptionsOrLoose } from '../internal/parseOptionsOrLoose';\nimport { reInvalidCharacter, reInvalidCharacterOrAmpersand } from '../const';\n\n/**\n * 檢查字串是否含無效字元\n * Check whether a string contains invalid characters\n *\n * 預設採用允許 `&` 的正則；要求 noAmpersand 時改用不允許 `&` 的正則，\n * 讓 ampersand 語法可被明確關閉。\n * By default the ampersand-tolerating regex is used; with noAmpersand the\n * ampersand-disallowing one is used instead, so the syntax can be switched off\n * explicitly.\n *\n * @param semver - 要檢查的字串 / String to check\n * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n * @returns 是否含無效字元 / Whether it contains invalid characters\n */\nexport function hasInvalidCharacter(semver: string,\n\toptionsOrLoose?: IOptionsOrLoose,\n)\n{\n\treturn (parseOptionsOrLoose(optionsOrLoose).noAmpersand\n\t\t? reInvalidCharacter\n\t\t: reInvalidCharacterOrAmpersand).test(semver)\n}\n\n/**\n * 斷言字串不含無效字元\n * Assert that a string contains no invalid characters\n *\n * 與 hasInvalidCharacter 同樣依 noAmpersand 選擇正則；\n * 例外訊息會帶出無效字元本身與其位置，方便除錯。\n * Uses the same noAmpersand-driven regex selection as hasInvalidCharacter;\n * the thrown message includes the offending character and its index to ease\n * debugging.\n *\n * @param semver - 要檢查的字串 / String to check\n * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n * @throws {TypeError} 當字串含無效字元時 / When the string contains invalid characters\n */\nexport function assertInvalidCharacter(semver: string,\n\toptionsOrLoose?: IOptionsOrLoose,\n): asserts semver is string\n{\n\tconst m = semver.match(parseOptionsOrLoose(optionsOrLoose).noAmpersand\n\t\t? reInvalidCharacter\n\t\t: reInvalidCharacterOrAmpersand);\n\n\tif (m?.length)\n\t{\n\t\tthrow new TypeError(`Invalid SemVer Character: '${m[0]}' at index ${m.index} of '${semver}'`)\n\t}\n}\n\n/**\n * 斷言比較器集合不是空的\n * Assert that a comparator set is not empty\n *\n * 空集合代表整個範圍無法解析成任何條件，\n * 回傳的訊息可由呼叫端覆寫，以帶上原始範圍字串。\n * An empty set means the whole range failed to parse into any condition; the\n * message can be overridden by the caller so the original range string is\n * included.\n *\n * @param comparatorsSet - 比較器集合 / Comparator set\n * @param message - 自訂錯誤訊息 / Custom error message\n * @throws {TypeError} 當集合為空時 / When the set is empty\n */\nexport function assertInvalidComparatorSet(comparatorsSet: IComparatorSetInput, message?: string): asserts comparatorsSet is IComparatorSetInput\n{\n\tif (!comparatorsSet?.length || !Array.isArray(comparatorsSet))\n\t{\n\t\tthrow new TypeError(message ?? `Invalid ComparatorSet: ${comparatorsSet}`)\n\t}\n}\n"]}

package/lib/util/fixBooleanProperty.d.ts

@@ -1,3 +1,18 @@
 import { ITSArrayListMaybeReadonly } from 'ts-type/lib/type/base';
+/** 需要被強制為布林值的預設選項欄位 / Default option fields that must be coerced to boolean */
 export declare const opts: readonly ["includePrerelease", "loose", "rtl"];
+/**
+ * 把選項中的指定欄位強制轉為布林值
+ * Coerce the given option fields to boolean
+ *
+ * 使用者常傳入 0/1、字串等非嚴格布林值，此函式統一成真正的 boolean，
+ * 避免 `if (options.loose)` 這類判斷在非預期型別下出現歧義。
+ * Callers often pass 0/1 or strings instead of a real boolean; this normalizes
+ * them so checks like `if (options.loose)` never behave ambiguously.
+ *
+ * @param options - 選項物件（會被原地修改）/ Options object (mutated in place)
+ * @param fields - 需要轉換的欄位，預設 opts / Fields to coerce, defaults to `opts`
+ * @param mode - true 時即使欄位不存在也補成 false / When true, missing fields are also materialized as false
+ * @returns 同一個選項物件 / The same options object
+ */
 export declare function fixBooleanProperty<T extends Record<any, any>>(options: T, fields?: ITSArrayListMaybeReadonly<string>, mode?: boolean): T;

package/lib/util/fixBooleanProperty.js

@@ -2,9 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.opts = void 0;
 exports.fixBooleanProperty = fixBooleanProperty;
+/** 需要被強制為布林值的預設選項欄位 / Default option fields that must be coerced to boolean */
 exports.opts = ['includePrerelease', 'loose', 'rtl'];
+/**
+ * 把選項中的指定欄位強制轉為布林值
+ * Coerce the given option fields to boolean
+ *
+ * 使用者常傳入 0/1、字串等非嚴格布林值，此函式統一成真正的 boolean，
+ * 避免 `if (options.loose)` 這類判斷在非預期型別下出現歧義。
+ * Callers often pass 0/1 or strings instead of a real boolean; this normalizes
+ * them so checks like `if (options.loose)` never behave ambiguously.
+ *
+ * @param options - 選項物件（會被原地修改）/ Options object (mutated in place)
+ * @param fields - 需要轉換的欄位，預設 opts / Fields to coerce, defaults to `opts`
+ * @param mode - true 時即使欄位不存在也補成 false / When true, missing fields are also materialized as false
+ * @returns 同一個選項物件 / The same options object
+ */
 function fixBooleanProperty(options, fields = exports.opts, mode) {
     fields.forEach(k => {
+        // mode 決定是否連未定義的欄位一起補值，預設只修正已存在的欄位
+        // `mode` decides whether undefined fields are materialized too; by
+        // default only fields that already exist are corrected
         if (typeof options[k] !== 'undefined' || mode === true) {
             // @ts-ignore
             options[k] = !!options[k];

package/lib/util/fixBooleanProperty.js.map

@@ -1 +1 @@
-{"version":3,"file":"fixBooleanProperty.js","sourceRoot":"","sources":["fixBooleanProperty.ts"],"names":[],"mappings":";;;AAIA,gDAeC;AAjBY,QAAA,IAAI,GAAG,CAAC,mBAAmB,EAAE,OAAO,EAAE,KAAK,CAAU,CAAA;AAElE,SAAgB,kBAAkB,CAA6B,OAAU,EACxE,SAA4C,YAAI,EAChD,IAAc;IAGd,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QAElB,IAAI,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,IAAI,KAAK,IAAI,EACtD,CAAC;YACA,aAAa;YACb,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["import { ITSArrayListMaybeReadonly } from 'ts-type/lib/type/base';\n\nexport const opts = ['includePrerelease', 'loose', 'rtl'] as const\n\nexport function fixBooleanProperty<T extends Record<any, any>>(options: T,\n\tfields: ITSArrayListMaybeReadonly<string> = opts,\n\tmode?: boolean\n)\n{\n\tfields.forEach(k =>\n\t{\n\t\tif (typeof options[k] !== 'undefined' || mode === true)\n\t\t{\n\t\t\t// @ts-ignore\n\t\t\toptions[k] = !!options[k];\n\t\t}\n\t});\n\n\treturn options\n}\n"]}
+{"version":3,"file":"fixBooleanProperty.js","sourceRoot":"","sources":["fixBooleanProperty.ts"],"names":[],"mappings":";;;AAmBA,gDAkBC;AAnCD,+EAA+E;AAClE,QAAA,IAAI,GAAG,CAAC,mBAAmB,EAAE,OAAO,EAAE,KAAK,CAAU,CAAA;AAElE;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB,CAA6B,OAAU,EACxE,SAA4C,YAAI,EAChD,IAAc;IAGd,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QAElB,mCAAmC;QACnC,mEAAmE;QACnE,uDAAuD;QACvD,IAAI,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,IAAI,KAAK,IAAI,EACtD,CAAC;YACA,aAAa;YACb,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["import { ITSArrayListMaybeReadonly } from 'ts-type/lib/type/base';\n\n/** 需要被強制為布林值的預設選項欄位 / Default option fields that must be coerced to boolean */\nexport const opts = ['includePrerelease', 'loose', 'rtl'] as const\n\n/**\n * 把選項中的指定欄位強制轉為布林值\n * Coerce the given option fields to boolean\n *\n * 使用者常傳入 0/1、字串等非嚴格布林值，此函式統一成真正的 boolean，\n * 避免 `if (options.loose)` 這類判斷在非預期型別下出現歧義。\n * Callers often pass 0/1 or strings instead of a real boolean; this normalizes\n * them so checks like `if (options.loose)` never behave ambiguously.\n *\n * @param options - 選項物件（會被原地修改）/ Options object (mutated in place)\n * @param fields - 需要轉換的欄位，預設 opts / Fields to coerce, defaults to `opts`\n * @param mode - true 時即使欄位不存在也補成 false / When true, missing fields are also materialized as false\n * @returns 同一個選項物件 / The same options object\n */\nexport function fixBooleanProperty<T extends Record<any, any>>(options: T,\n\tfields: ITSArrayListMaybeReadonly<string> = opts,\n\tmode?: boolean\n)\n{\n\tfields.forEach(k =>\n\t{\n\t\t// mode 決定是否連未定義的欄位一起補值，預設只修正已存在的欄位\n\t\t// `mode` decides whether undefined fields are materialized too; by\n\t\t// default only fields that already exist are corrected\n\t\tif (typeof options[k] !== 'undefined' || mode === true)\n\t\t{\n\t\t\t// @ts-ignore\n\t\t\toptions[k] = !!options[k];\n\t\t}\n\t});\n\n\treturn options\n}\n"]}

package/lib/util/index.d.ts

@@ -1,2 +1,26 @@
+/**
+ * 檢查字串是否包含 ampersand 或空白
+ * Check whether a string contains an ampersand or whitespace
+ *
+ * 用於快速判斷是否需要走 handleAmpersandAndSpaces 的字串正規化。
+ * Used as a fast pre-check for whether string normalization via
+ * handleAmpersandAndSpaces is needed at all.
+ *
+ * @param input - 輸入字串 / Input string
+ * @returns 是否含 `&` 或空白 / Whether it contains `&` or whitespace
+ */
 export declare function hasAmpersandAndSpaces(input: string): boolean;
+/**
+ * 判斷是否為純物件（plain object）
+ * Check whether a value is a plain object
+ *
+ * 除了原型必須是 Object.prototype 或 null，還先檢查
+ * Object.prototype.toString，以排除跨 realm 的物件與類陣列型別。
+ * Besides requiring the prototype to be Object.prototype or null, the
+ * Object.prototype.toString check up front rules out cross-realm objects and
+ * array-likes.
+ *
+ * @param value - 要檢查的值 / Value to check
+ * @returns 是否為純物件 / Whether it is a plain object
+ */
 export declare function isPlainObject(value: any): value is object;

package/lib/util/index.js

@@ -3,9 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasAmpersandAndSpaces = hasAmpersandAndSpaces;
 exports.isPlainObject = isPlainObject;
 const const_1 = require("../const");
+/**
+ * 檢查字串是否包含 ampersand 或空白
+ * Check whether a string contains an ampersand or whitespace
+ *
+ * 用於快速判斷是否需要走 handleAmpersandAndSpaces 的字串正規化。
+ * Used as a fast pre-check for whether string normalization via
+ * handleAmpersandAndSpaces is needed at all.
+ *
+ * @param input - 輸入字串 / Input string
+ * @returns 是否含 `&` 或空白 / Whether it contains `&` or whitespace
+ */
 function hasAmpersandAndSpaces(input) {
     return const_1.reAmpersandAndSpaces.test(input);
 }
+/**
+ * 判斷是否為純物件（plain object）
+ * Check whether a value is a plain object
+ *
+ * 除了原型必須是 Object.prototype 或 null，還先檢查
+ * Object.prototype.toString，以排除跨 realm 的物件與類陣列型別。
+ * Besides requiring the prototype to be Object.prototype or null, the
+ * Object.prototype.toString check up front rules out cross-realm objects and
+ * array-likes.
+ *
+ * @param value - 要檢查的值 / Value to check
+ * @returns 是否為純物件 / Whether it is a plain object
+ */
 function isPlainObject(value) {
     if (Object.prototype.toString.call(value) !== '[object Object]') {
         return false;

package/lib/util/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;AAEA,sDAGC;AAED,sCASC;AAhBD,oCAAgD;AAEhD,SAAgB,qBAAqB,CAAC,KAAa;IAElD,OAAO,4BAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED,SAAgB,aAAa,CAAC,KAAK;IAElC,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,EAC/D,CAAC;QACA,OAAO,KAAK,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,CAAC;AAC7D,CAAC","sourcesContent":["import { reAmpersandAndSpaces } from '../const';\n\nexport function hasAmpersandAndSpaces(input: string)\n{\n\treturn reAmpersandAndSpaces.test(input)\n}\n\nexport function isPlainObject(value): value is object\n{\n\tif (Object.prototype.toString.call(value) !== '[object Object]')\n\t{\n\t\treturn false;\n\t}\n\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === null || prototype === Object.prototype;\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;AAaA,sDAGC;AAeD,sCASC;AAxCD,oCAAgD;AAEhD;;;;;;;;;;GAUG;AACH,SAAgB,qBAAqB,CAAC,KAAa;IAElD,OAAO,4BAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,aAAa,CAAC,KAAK;IAElC,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,EAC/D,CAAC;QACA,OAAO,KAAK,CAAC;IACd,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,CAAC;AAC7D,CAAC","sourcesContent":["import { reAmpersandAndSpaces } from '../const';\n\n/**\n * 檢查字串是否包含 ampersand 或空白\n * Check whether a string contains an ampersand or whitespace\n *\n * 用於快速判斷是否需要走 handleAmpersandAndSpaces 的字串正規化。\n * Used as a fast pre-check for whether string normalization via\n * handleAmpersandAndSpaces is needed at all.\n *\n * @param input - 輸入字串 / Input string\n * @returns 是否含 `&` 或空白 / Whether it contains `&` or whitespace\n */\nexport function hasAmpersandAndSpaces(input: string)\n{\n\treturn reAmpersandAndSpaces.test(input)\n}\n\n/**\n * 判斷是否為純物件（plain object）\n * Check whether a value is a plain object\n *\n * 除了原型必須是 Object.prototype 或 null，還先檢查\n * Object.prototype.toString，以排除跨 realm 的物件與類陣列型別。\n * Besides requiring the prototype to be Object.prototype or null, the\n * Object.prototype.toString check up front rules out cross-realm objects and\n * array-likes.\n *\n * @param value - 要檢查的值 / Value to check\n * @returns 是否為純物件 / Whether it is a plain object\n */\nexport function isPlainObject(value): value is object\n{\n\tif (Object.prototype.toString.call(value) !== '[object Object]')\n\t{\n\t\treturn false;\n\t}\n\n\tconst prototype = Object.getPrototypeOf(value);\n\treturn prototype === null || prototype === Object.prototype;\n}\n"]}

package/lib/util/split.d.ts

@@ -1,2 +1,19 @@
+/**
+ * 依 `||` 切割範圍字串，且不保留分隔符
+ * Split a range string on `||` without keeping the separator
+ *
+ * brackets: true 讓括號內的 `||`（如 peerdep 群組）不被切開，
+ * 拆掉分隔符是因為呼叫端會自行補回 ` || `。
+ * `brackets: true` keeps `||` inside brackets intact (e.g. peer-dependency
+ * groups); the separator is dropped because callers re-add ` || ` themselves.
+ */
 export declare const splitDoubleVerticalBar: (str: string) => string[];
+/**
+ * 依空白切割範圍字串，且不保留分隔符
+ * Split a range string on whitespace without keeping the separator
+ *
+ * 與 splitDoubleVerticalBar 相同的括號保護，避免切開括號內的空白。
+ * Same bracket protection as splitDoubleVerticalBar, so whitespace inside
+ * brackets is not split.
+ */
 export declare const splitSpace: (str: string) => string[];

package/lib/util/split.js

@@ -3,10 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitSpace = exports.splitDoubleVerticalBar = void 0;
 const split_smartly2_1 = require("split-smartly2");
 const const_1 = require("../const");
+/**
+ * 依 `||` 切割範圍字串，且不保留分隔符
+ * Split a range string on `||` without keeping the separator
+ *
+ * brackets: true 讓括號內的 `||`（如 peerdep 群組）不被切開，
+ * 拆掉分隔符是因為呼叫端會自行補回 ` || `。
+ * `brackets: true` keeps `||` inside brackets intact (e.g. peer-dependency
+ * groups); the separator is dropped because callers re-add ` || ` themselves.
+ */
 exports.splitDoubleVerticalBar = (0, split_smartly2_1.splitSmartly)(const_1.reDoubleVerticalBar, {
     includeSeparatorMode: "NONE" /* EnumIncludeSeparatorMode.INCLUDE_SEPARATOR_NONE */,
     brackets: true,
 });
+/**
+ * 依空白切割範圍字串，且不保留分隔符
+ * Split a range string on whitespace without keeping the separator
+ *
+ * 與 splitDoubleVerticalBar 相同的括號保護，避免切開括號內的空白。
+ * Same bracket protection as splitDoubleVerticalBar, so whitespace inside
+ * brackets is not split.
+ */
 exports.splitSpace = (0, split_smartly2_1.splitSmartly)(const_1.reSpaces, {
     includeSeparatorMode: "NONE" /* EnumIncludeSeparatorMode.INCLUDE_SEPARATOR_NONE */,
     brackets: true,

package/lib/util/split.js.map

@@ -1 +1 @@
-{"version":3,"file":"split.js","sourceRoot":"","sources":["split.ts"],"names":[],"mappings":";;;AAAA,mDAAwE;AACxE,oCAAyD;AAE5C,QAAA,sBAAsB,GAAG,IAAA,6BAAY,EAAC,2BAAmB,EAAE;IACvE,oBAAoB,8DAAiD;IACrE,QAAQ,EAAE,IAAI;CACd,CAA8B,CAAC;AAEnB,QAAA,UAAU,GAAG,IAAA,6BAAY,EAAC,gBAAQ,EAAE;IAChD,oBAAoB,8DAAiD;IACrE,QAAQ,EAAE,IAAI;CACd,CAA8B,CAAC","sourcesContent":["import { splitSmartly, EnumIncludeSeparatorMode } from 'split-smartly2';\nimport { reDoubleVerticalBar, reSpaces } from '../const';\n\nexport const splitDoubleVerticalBar = splitSmartly(reDoubleVerticalBar, {\n\tincludeSeparatorMode: EnumIncludeSeparatorMode.INCLUDE_SEPARATOR_NONE,\n\tbrackets: true,\n}) as (str: string) => string[];\n\nexport const splitSpace = splitSmartly(reSpaces, {\n\tincludeSeparatorMode: EnumIncludeSeparatorMode.INCLUDE_SEPARATOR_NONE,\n\tbrackets: true,\n}) as (str: string) => string[];\n"]}
+{"version":3,"file":"split.js","sourceRoot":"","sources":["split.ts"],"names":[],"mappings":";;;AAAA,mDAAwE;AACxE,oCAAyD;AAEzD;;;;;;;;GAQG;AACU,QAAA,sBAAsB,GAAG,IAAA,6BAAY,EAAC,2BAAmB,EAAE;IACvE,oBAAoB,8DAAiD;IACrE,QAAQ,EAAE,IAAI;CACd,CAA8B,CAAC;AAEhC;;;;;;;GAOG;AACU,QAAA,UAAU,GAAG,IAAA,6BAAY,EAAC,gBAAQ,EAAE;IAChD,oBAAoB,8DAAiD;IACrE,QAAQ,EAAE,IAAI;CACd,CAA8B,CAAC","sourcesContent":["import { splitSmartly, EnumIncludeSeparatorMode } from 'split-smartly2';\nimport { reDoubleVerticalBar, reSpaces } from '../const';\n\n/**\n * 依 `||` 切割範圍字串，且不保留分隔符\n * Split a range string on `||` without keeping the separator\n *\n * brackets: true 讓括號內的 `||`（如 peerdep 群組）不被切開，\n * 拆掉分隔符是因為呼叫端會自行補回 ` || `。\n * `brackets: true` keeps `||` inside brackets intact (e.g. peer-dependency\n * groups); the separator is dropped because callers re-add ` || ` themselves.\n */\nexport const splitDoubleVerticalBar = splitSmartly(reDoubleVerticalBar, {\n\tincludeSeparatorMode: EnumIncludeSeparatorMode.INCLUDE_SEPARATOR_NONE,\n\tbrackets: true,\n}) as (str: string) => string[];\n\n/**\n * 依空白切割範圍字串，且不保留分隔符\n * Split a range string on whitespace without keeping the separator\n *\n * 與 splitDoubleVerticalBar 相同的括號保護，避免切開括號內的空白。\n * Same bracket protection as splitDoubleVerticalBar, so whitespace inside\n * brackets is not split.\n */\nexport const splitSpace = splitSmartly(reSpaces, {\n\tincludeSeparatorMode: EnumIncludeSeparatorMode.INCLUDE_SEPARATOR_NONE,\n\tbrackets: true,\n}) as (str: string) => string[];\n"]}

package/lib/util/stringifyComparators.d.ts

@@ -1,3 +1,21 @@
 import { IComparatorSetInput, IComparatorArrayInput } from '../types';
+/**
+ * 把單一比較器陣列組成字串（以空白分隔）
+ * Join one comparator array into a string (space-separated)
+ *
+ * @param comparatorsArray - 比較器陣列 / Comparator array
+ * @returns 比較器字串 / Comparator string
+ */
 export declare function stringifyComparators(comparatorsArray: IComparatorArrayInput): string;
+/**
+ * 把整個比較器集合組成範圍字串
+ * Join a whole comparator set into a range string
+ *
+ * 外層以 ` || ` 分隔（含前後空白），讓輸出可直接再喂回解析器。
+ * Groups are joined with ` || ` (including surrounding spaces) so the output
+ * can be fed straight back into the parser.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @returns 範圍字串 / Range string
+ */
 export declare function stringifyComparatorsSet(comparatorsSet: IComparatorSetInput): string;

package/lib/util/stringifyComparators.js

@@ -3,9 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.stringifyComparators = stringifyComparators;
 exports.stringifyComparatorsSet = stringifyComparatorsSet;
 const const_1 = require("../const");
+/**
+ * 把單一比較器陣列組成字串（以空白分隔）
+ * Join one comparator array into a string (space-separated)
+ *
+ * @param comparatorsArray - 比較器陣列 / Comparator array
+ * @returns 比較器字串 / Comparator string
+ */
 function stringifyComparators(comparatorsArray) {
     return comparatorsArray.join(' ');
 }
+/**
+ * 把整個比較器集合組成範圍字串
+ * Join a whole comparator set into a range string
+ *
+ * 外層以 ` || ` 分隔（含前後空白），讓輸出可直接再喂回解析器。
+ * Groups are joined with ` || ` (including surrounding spaces) so the output
+ * can be fed straight back into the parser.
+ *
+ * @param comparatorsSet - 比較器集合 / Comparator set
+ * @returns 範圍字串 / Range string
+ */
 function stringifyComparatorsSet(comparatorsSet) {
     return comparatorsSet
         .map(stringifyComparators)

package/lib/util/stringifyComparators.js.map

@@ -1 +1 @@
-{"version":3,"file":"stringifyComparators.js","sourceRoot":"","sources":["stringifyComparators.ts"],"names":[],"mappings":";;AAIA,oDAGC;AAED,0DAMC;AAdD,oCAAsD;AAGtD,SAAgB,oBAAoB,CAAC,gBAAuC;IAE3E,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAClC,CAAC;AAED,SAAgB,uBAAuB,CAAC,cAAmC;IAE1E,OAAO,cAAc;SACnB,GAAG,CAAC,oBAAoB,CAAC;SACzB,IAAI,CAAC,kCAA0B,CAAC,CACjC;AACF,CAAC","sourcesContent":["\nimport { separatorDoubleVerticalBar } from '../const';\nimport { IComparatorSetInput, IComparatorArrayInput } from '../types';\n\nexport function stringifyComparators(comparatorsArray: IComparatorArrayInput)\n{\n\treturn comparatorsArray.join(' ')\n}\n\nexport function stringifyComparatorsSet(comparatorsSet: IComparatorSetInput)\n{\n\treturn comparatorsSet\n\t\t.map(stringifyComparators)\n\t\t.join(separatorDoubleVerticalBar)\n\t;\n}\n"]}
+{"version":3,"file":"stringifyComparators.js","sourceRoot":"","sources":["stringifyComparators.ts"],"names":[],"mappings":";;AAWA,oDAGC;AAaD,0DAMC;AAhCD,oCAAsD;AAGtD;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAAC,gBAAuC;IAE3E,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAClC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,uBAAuB,CAAC,cAAmC;IAE1E,OAAO,cAAc;SACnB,GAAG,CAAC,oBAAoB,CAAC;SACzB,IAAI,CAAC,kCAA0B,CAAC,CACjC;AACF,CAAC","sourcesContent":["\nimport { separatorDoubleVerticalBar } from '../const';\nimport { IComparatorSetInput, IComparatorArrayInput } from '../types';\n\n/**\n * 把單一比較器陣列組成字串（以空白分隔）\n * Join one comparator array into a string (space-separated)\n *\n * @param comparatorsArray - 比較器陣列 / Comparator array\n * @returns 比較器字串 / Comparator string\n */\nexport function stringifyComparators(comparatorsArray: IComparatorArrayInput)\n{\n\treturn comparatorsArray.join(' ')\n}\n\n/**\n * 把整個比較器集合組成範圍字串\n * Join a whole comparator set into a range string\n *\n * 外層以 ` || ` 分隔（含前後空白），讓輸出可直接再喂回解析器。\n * Groups are joined with ` || ` (including surrounding spaces) so the output\n * can be fed straight back into the parser.\n *\n * @param comparatorsSet - 比較器集合 / Comparator set\n * @returns 範圍字串 / Range string\n */\nexport function stringifyComparatorsSet(comparatorsSet: IComparatorSetInput)\n{\n\treturn comparatorsSet\n\t\t.map(stringifyComparators)\n\t\t.join(separatorDoubleVerticalBar)\n\t;\n}\n"]}

package/lib/validRange.d.ts

@@ -1,6 +1,20 @@
 import { IOptionsOrLoose } from './types';
 /**
- * Return the valid range or null if it's not valid
+ * 回傳規範化後的範圍，無效時回傳 null
+ * Return the valid range, or null if it's not valid
+ *
+ * 先以正則過濾無效字元（依 noAmpersand 決定 `&` 是否算無效），
+ * 再交由 Range 嘗試解析；任何解析例外都會被吞掉並統一回傳 null，
+ * 讓呼叫端只用「truthy / null」即可判斷，不必自行包 try/catch。
+ * Invalid characters are filtered first (whether `&` counts as invalid depends
+ * on noAmpersand), then Range tries to parse; any parsing error is swallowed
+ * and normalized to null so callers only need a truthy/null check instead of
+ * wrapping their own try/catch.
+ *
+ * @param range - 範圍字串 / Range string
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 規範化後的範圍字串，無效時為 null / Normalized range string, or null when invalid
+ * @throws {TypeError} 當 range 不是字串時 / When range is not a string
  */
 export declare function validRange(range: string, optionsOrLoose?: IOptionsOrLoose): string;
 export default validRange;

package/lib/validRange.js

@@ -6,7 +6,21 @@ const parseOptionsOrLoose_1 = require("./internal/parseOptionsOrLoose");
 const Range_1 = tslib_1.__importDefault(require("./Range"));
 const assert_1 = require("./util/assert");
 /**
- * Return the valid range or null if it's not valid
+ * 回傳規範化後的範圍，無效時回傳 null
+ * Return the valid range, or null if it's not valid
+ *
+ * 先以正則過濾無效字元（依 noAmpersand 決定 `&` 是否算無效），
+ * 再交由 Range 嘗試解析；任何解析例外都會被吞掉並統一回傳 null，
+ * 讓呼叫端只用「truthy / null」即可判斷，不必自行包 try/catch。
+ * Invalid characters are filtered first (whether `&` counts as invalid depends
+ * on noAmpersand), then Range tries to parse; any parsing error is swallowed
+ * and normalized to null so callers only need a truthy/null check instead of
+ * wrapping their own try/catch.
+ *
+ * @param range - 範圍字串 / Range string
+ * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag
+ * @returns 規範化後的範圍字串，無效時為 null / Normalized range string, or null when invalid
+ * @throws {TypeError} 當 range 不是字串時 / When range is not a string
  */
 function validRange(range, optionsOrLoose) {
     if (typeof range !== 'string') {

package/lib/validRange.js.map

@@ -1 +1 @@
-{"version":3,"file":"validRange.js","sourceRoot":"","sources":["validRange.ts"],"names":[],"mappings":";;AASA,gCAsBC;;AA9BD,wEAAqE;AACrE,4DAAkC;AAElC,0CAAoD;AAEpD;;GAEG;AACH,SAAgB,UAAU,CAAC,KAAa,EAAE,cAAgC;IAEzE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAC7B,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,mCAAmC,KAAK,EAAE,CAAC,CAAA;IAChE,CAAC;IAED,cAAc,GAAG,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAA;IAEpD,IACA,CAAC;QACA,IAAI,CAAC,IAAA,4BAAmB,EAAC,KAAK,EAAE,cAAc,CAAC,EAC/C,CAAC;YACA,OAAO,IAAI,eAAW,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,aAAa,EAAE,CAAA;QAC9D,CAAC;IACF,CAAC;IACD,OAAO,EAAE,EACT,CAAC;IAED,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,kBAAe,UAAU,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { parseOptionsOrLoose } from './internal/parseOptionsOrLoose';\nimport SemverRange from './Range';\nimport { IOptionsOrLoose } from './types';\nimport { hasInvalidCharacter } from './util/assert';\n\n/**\n * Return the valid range or null if it's not valid\n */\nexport function validRange(range: string, optionsOrLoose?: IOptionsOrLoose)\n{\n\tif (typeof range !== 'string')\n\t{\n\t\tthrow new TypeError(`range should be string, but got ${range}`)\n\t}\n\n\toptionsOrLoose = parseOptionsOrLoose(optionsOrLoose)\n\n\ttry\n\t{\n\t\tif (!hasInvalidCharacter(range, optionsOrLoose))\n\t\t{\n\t\t\treturn new SemverRange(range, optionsOrLoose).toRangeString()\n\t\t}\n\t}\n\tcatch (er)\n\t{\n\n\t}\n\n\treturn null\n}\n\nexport default validRange\n"]}
+{"version":3,"file":"validRange.js","sourceRoot":"","sources":["validRange.ts"],"names":[],"mappings":";;AAuBA,gCAsBC;;AA5CD,wEAAqE;AACrE,4DAAkC;AAElC,0CAAoD;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,UAAU,CAAC,KAAa,EAAE,cAAgC;IAEzE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAC7B,CAAC;QACA,MAAM,IAAI,SAAS,CAAC,mCAAmC,KAAK,EAAE,CAAC,CAAA;IAChE,CAAC;IAED,cAAc,GAAG,IAAA,yCAAmB,EAAC,cAAc,CAAC,CAAA;IAEpD,IACA,CAAC;QACA,IAAI,CAAC,IAAA,4BAAmB,EAAC,KAAK,EAAE,cAAc,CAAC,EAC/C,CAAC;YACA,OAAO,IAAI,eAAW,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,aAAa,EAAE,CAAA;QAC9D,CAAC;IACF,CAAC;IACD,OAAO,EAAE,EACT,CAAC;IAED,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED,kBAAe,UAAU,CAAA","sourcesContent":["import SemVer from 'semver/classes/semver';\nimport { parseOptionsOrLoose } from './internal/parseOptionsOrLoose';\nimport SemverRange from './Range';\nimport { IOptionsOrLoose } from './types';\nimport { hasInvalidCharacter } from './util/assert';\n\n/**\n * 回傳規範化後的範圍，無效時回傳 null\n * Return the valid range, or null if it's not valid\n *\n * 先以正則過濾無效字元（依 noAmpersand 決定 `&` 是否算無效），\n * 再交由 Range 嘗試解析；任何解析例外都會被吞掉並統一回傳 null，\n * 讓呼叫端只用「truthy / null」即可判斷，不必自行包 try/catch。\n * Invalid characters are filtered first (whether `&` counts as invalid depends\n * on noAmpersand), then Range tries to parse; any parsing error is swallowed\n * and normalized to null so callers only need a truthy/null check instead of\n * wrapping their own try/catch.\n *\n * @param range - 範圍字串 / Range string\n * @param optionsOrLoose - 選項或寬鬆旗標 / Options or loose flag\n * @returns 規範化後的範圍字串，無效時為 null / Normalized range string, or null when invalid\n * @throws {TypeError} 當 range 不是字串時 / When range is not a string\n */\nexport function validRange(range: string, optionsOrLoose?: IOptionsOrLoose)\n{\n\tif (typeof range !== 'string')\n\t{\n\t\tthrow new TypeError(`range should be string, but got ${range}`)\n\t}\n\n\toptionsOrLoose = parseOptionsOrLoose(optionsOrLoose)\n\n\ttry\n\t{\n\t\tif (!hasInvalidCharacter(range, optionsOrLoose))\n\t\t{\n\t\t\treturn new SemverRange(range, optionsOrLoose).toRangeString()\n\t\t}\n\t}\n\tcatch (er)\n\t{\n\n\t}\n\n\treturn null\n}\n\nexport default validRange\n"]}