@yarn-tool/pkg-version-query 3.0.9 → 3.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,59 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
+ ## [3.0.11](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/pkg-version-query@3.0.10...@yarn-tool/pkg-version-query@3.0.11) (2026-10-12)
7
+
8
+
9
+
10
+ ### 📚 Documentation
11
+
12
+ * add jsdoc ([9cb9b13](https://github.com/bluelovers/ws-yarn-workspaces/commit/9cb9b13eda8c357221ad1b754458aa9916eada22))
13
+
14
+
15
+ ### 🚨 Tests
16
+
17
+ * **snap:** update snapshots ([c9945a5](https://github.com/bluelovers/ws-yarn-workspaces/commit/c9945a5b9cd723d38ded2a69b83e2e83ecc3b524))
18
+ * **test:** 將測試框架從 jest 遷移至 node:test ([3af9774](https://github.com/bluelovers/ws-yarn-workspaces/commit/3af9774964abc48083ec60b2021c1cec08874803))
19
+
20
+
21
+ ### 🛠 Build System
22
+
23
+ * update build ([3186340](https://github.com/bluelovers/ws-yarn-workspaces/commit/3186340758172427cb1e9b8955f6fd677abac625))
24
+ * **deps:** 更新測試腳本與依賴以支援 node:test ([f9c71c7](https://github.com/bluelovers/ws-yarn-workspaces/commit/f9c71c795c792c5c7ed9d613ce7e9c3c726c39d5))
25
+
26
+
27
+ ### ♻️ Chores
28
+
29
+ * **deps:** 更新各套件依賴版本 ([569f075](https://github.com/bluelovers/ws-yarn-workspaces/commit/569f0756189cdadf69955d8e388ac0a6a8988056))
30
+ * **workspace:** 更新測試指令路徑與新增工作區搜尋選項 ([a80039d](https://github.com/bluelovers/ws-yarn-workspaces/commit/a80039dd8c691e047466966ffc8f8a4e2e31c03f))
31
+
32
+
33
+ ### 🔖 Miscellaneous
34
+
35
+ * . ([e5788f8](https://github.com/bluelovers/ws-yarn-workspaces/commit/e5788f84551b870490a96d0a5d67d8d542481373))
36
+
37
+
38
+
39
+ ## [3.0.10](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/pkg-version-query@3.0.9...@yarn-tool/pkg-version-query@3.0.10) (2026-09-06)
40
+
41
+
42
+
43
+ ### 🛠 Build System
44
+
45
+ * update Static Files ([b2f5d72](https://github.com/bluelovers/ws-yarn-workspaces/commit/b2f5d7216773c53eb35f267ba34f8788543d46a1))
46
+
47
+
48
+ ### ♻️ Chores
49
+
50
+ * **workspace:** 將所有套件的指令從 yarn 改為 pnpm 並更新依賴版本 ([0505892](https://github.com/bluelovers/ws-yarn-workspaces/commit/0505892e5e7c356f8cf59495fefda1aa681499c6))
51
+
52
+
53
+ ### 🔖 Miscellaneous
54
+
55
+ * . ([b545589](https://github.com/bluelovers/ws-yarn-workspaces/commit/b54558925d67304019e2b4f9bb3c4671c429a96e))
56
+
57
+
58
+
6
59
  ## [3.0.9](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/pkg-version-query@3.0.8...@yarn-tool/pkg-version-query@3.0.9) (2026-04-26)
7
60
 
8
61
 
package/README.md CHANGED
@@ -70,7 +70,7 @@ import { queryVersionByNpmPackageArgWithCache } from '@yarn-tool/pkg-version-que
70
70
  const version = await queryVersionByNpmPackageArgWithCache('lodash@^4.0.0');
71
71
  ```
72
72
 
73
- ## API Reference / API 參考
73
+ ## API Documentation / API 文件
74
74
 
75
75
  ### `queryVersionWithCache(name, targetVersion?, options?)`
76
76
 
@@ -123,6 +123,39 @@ interface IOptionsQueryVersion {
123
123
  }
124
124
  ```
125
125
 
126
+ ## Configuration / 設定
127
+
128
+ 本套件沒有設定檔 (Config File),行為完全由查詢函式傳入的 `options`(`IOptionsQueryVersion`)決定:
129
+
130
+ | 選項 | 型別 | 預設 | 說明 |
131
+ | --- | --- | --- | --- |
132
+ | `notThrowError` | `boolean` | `false` | 查詢失敗時回傳 `undefined` 而非丟出例外 (Return `undefined` instead of throwing) |
133
+ | `cacheAgent` | `Cache<string, ICachedVersionResult>` | 內建單例 (Built-in Singleton) | 自訂快取實例 (Cache Instance),傳入後即不使用內建快取 |
134
+ | `cacheAgentOptions` | `IOptionsLRUCacheFS<string, ICachedVersionResult>` | 見下方預設值 | 傳給 `lru-cache-fs2` 的快取設定 |
135
+
136
+ 其餘欄位會原樣轉交給底層的 `package-json`(例如自訂 npm registry 的相關選項)。
137
+
138
+ 快取 (Cache) 的行為由 `initCache()` 決定:
139
+
140
+ - 快取目錄由 `cache-path` 依序嘗試 `findYarnCachePath` → `findNpmCachePath` → `findOSTempPath` → `findPkgModulePath`,並以套件名稱 `@yarn-tool/pkg-version-query` 作為快取名稱 (Cache Name)。
141
+ - `max` 未設定或 `<= 100` 時會被提升為 `1000`,避免快取過小導致頻繁的 registry 查詢。
142
+ - `maxAge` 未設定或 `<= 1 分鐘` 時會被提升為 `10 分鐘`,避免版本資料過期過快。
143
+ - `getCache()` 回傳模組層級的單例 (Module-level Singleton),首次建立後重複使用;若需完全隔離的快取,請自行傳入 `cacheAgent`。
144
+
145
+ ```typescript
146
+ import { queryVersionWithCache } from '@yarn-tool/pkg-version-query';
147
+
148
+ const version = await queryVersionWithCache('lodash', 'latest', {
149
+ notThrowError: true,
150
+ cacheAgentOptions: {
151
+ max: 1000,
152
+ maxAge: 10 * 60 * 1000,
153
+ },
154
+ });
155
+ ```
156
+
157
+ This module has no config file; everything is driven by the `options` passed to the query functions. The cache directory is resolved in order: yarn cache → npm cache → OS temp dir → node_modules path. `max` is raised to `1000` and `maxAge` to `10 minutes` when unset or below the built-in floors, and `getCache()` returns a module-level singleton unless you supply your own `cacheAgent`.
158
+
126
159
  ## Related Packages / 相關套件
127
160
 
128
161
  - [@yarn-tool/ncu](../ncu) - npm-check-updates wrapper using this package
package/index.d.ts CHANGED
@@ -20,6 +20,15 @@
20
20
  import { queryVersionByNpmPackageArgWithCache } from './lib/queryVersionByNpmPackageArg';
21
21
  import { queryVersionWithCache } from './lib/queryVersion';
22
22
  import { getCache } from './lib/cacheAgent';
23
+ /**
24
+ * 對外 API 面 (Public API Surface):
25
+ * 預設匯出 queryVersionWithCache,另提供 npm 套件參數查詢與快取操作;
26
+ * 型別刻意以 type-only 匯出,避免載入執行期程式碼時連帶引進多餘的相依。
27
+ *
28
+ * Public API: queryVersionWithCache is the default export, plus the npm-package-argument
29
+ * variant and cache access; types are re-exported type-only so pulling in the types
30
+ * does not drag in extra runtime code.
31
+ */
23
32
  export type { ICachedVersionResult, IOptionsQueryVersion } from './lib/types';
24
33
  export { queryVersionByNpmPackageArgWithCache };
25
34
  export { queryVersionWithCache };
package/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,mFAAyF;AAMhF,qHANA,kEAAoC,OAMA;AAL7C,qDAA2D;AAMlD,sGANA,oCAAqB,OAMA;AAL9B,iDAA4C;AAOnC,yFAPA,qBAAQ,OAOA;AAEjB,kBAAe,oCAAqB,CAAA","sourcesContent":["/**\n * @yarn-tool/pkg-version-query\n *\n * Query package versions from npm registry with LRU cache support.\n * 從 npm registry 查詢套件版本,支援 LRU 快取機制。\n *\n * @packageDocumentation\n *\n * @example\n * ```ts\n * import queryVersionWithCache from '@yarn-tool/pkg-version-query';\n *\n * // Query latest version\n * const version = await queryVersionWithCache('lodash');\n *\n * // Query specific version range\n * const version = await queryVersionWithCache('typescript', '^4.0.0');\n * ```\n */\n\nimport { queryVersionByNpmPackageArgWithCache } from './lib/queryVersionByNpmPackageArg';\nimport { queryVersionWithCache } from './lib/queryVersion';\nimport { getCache } from './lib/cacheAgent';\n\nexport type { ICachedVersionResult, IOptionsQueryVersion } from './lib/types';\n\nexport { queryVersionByNpmPackageArgWithCache }\nexport { queryVersionWithCache }\n\nexport { getCache }\n\nexport default queryVersionWithCache\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,mFAAyF;AAehF,qHAfA,kEAAoC,OAeA;AAd7C,qDAA2D;AAelD,sGAfA,oCAAqB,OAeA;AAd9B,iDAA4C;AAgBnC,yFAhBA,qBAAQ,OAgBA;AAEjB,kBAAe,oCAAqB,CAAA","sourcesContent":["/**\n * @yarn-tool/pkg-version-query\n *\n * Query package versions from npm registry with LRU cache support.\n * 從 npm registry 查詢套件版本,支援 LRU 快取機制。\n *\n * @packageDocumentation\n *\n * @example\n * ```ts\n * import queryVersionWithCache from '@yarn-tool/pkg-version-query';\n *\n * // Query latest version\n * const version = await queryVersionWithCache('lodash');\n *\n * // Query specific version range\n * const version = await queryVersionWithCache('typescript', '^4.0.0');\n * ```\n */\n\nimport { queryVersionByNpmPackageArgWithCache } from './lib/queryVersionByNpmPackageArg';\nimport { queryVersionWithCache } from './lib/queryVersion';\nimport { getCache } from './lib/cacheAgent';\n\n/**\n * 對外 API 面 (Public API Surface):\n * 預設匯出 queryVersionWithCache,另提供 npm 套件參數查詢與快取操作;\n * 型別刻意以 type-only 匯出,避免載入執行期程式碼時連帶引進多餘的相依。\n *\n * Public API: queryVersionWithCache is the default export, plus the npm-package-argument\n * variant and cache access; types are re-exported type-only so pulling in the types\n * does not drag in extra runtime code.\n */\nexport type { ICachedVersionResult, IOptionsQueryVersion } from './lib/types';\n\nexport { queryVersionByNpmPackageArgWithCache }\nexport { queryVersionWithCache }\n\nexport { getCache }\n\nexport default queryVersionWithCache\n"]}
@@ -1,5 +1,25 @@
1
1
  import Cache from 'lru-cache-fs2';
2
2
  import { ICachedVersionResult, IOptionsQueryVersion } from './types';
3
3
  import { Options } from 'package-json';
4
+ /**
5
+ * 建立檔案後盾的 LRU 快取 (File-backed LRU Cache) 實例。
6
+ *
7
+ * Creates the file-backed LRU cache instance.
8
+ *
9
+ * @param options 查詢選項,僅取用其中的 cacheAgentOptions / Query options; only cacheAgentOptions is used
10
+ * @returns 新的快取實例 / A fresh cache instance
11
+ */
4
12
  export declare function initCache(options?: IOptionsQueryVersion<Options>): Cache<string, ICachedVersionResult>;
13
+ /**
14
+ * 取得快取實例:優先使用呼叫端自帶的 cacheAgent,
15
+ * 否則以 `??=` 惰性建立並重複使用同一個單例,
16
+ * 讓多處查詢共享同一份磁碟快取而不必各自初始化。
17
+ *
18
+ * Returns the cache instance: a caller-supplied cacheAgent wins, otherwise a
19
+ * module-level singleton is created lazily via `??=` so scattered queries share
20
+ * one disk-backed cache instead of each initialising their own.
21
+ *
22
+ * @param options 查詢選項,可攜帶 cacheAgent / Query options; may carry a custom cacheAgent
23
+ * @returns 快取實例 / The cache instance
24
+ */
5
25
  export declare function getCache(options?: IOptionsQueryVersion<Options>): Cache<string, ICachedVersionResult>;
package/lib/cacheAgent.js CHANGED
@@ -5,9 +5,32 @@ exports.getCache = getCache;
5
5
  const tslib_1 = require("tslib");
6
6
  const lru_cache_fs2_1 = tslib_1.__importDefault(require("lru-cache-fs2"));
7
7
  const cache_path_1 = require("cache-path");
8
+ /**
9
+ * 模組層級的快取單例 (Module-level Cache Singleton);
10
+ * 以 `??=` 延後初始化,確保只有第一次 getCache() 才會建立快取並產生磁碟 IO。
11
+ *
12
+ * Module-level cache singleton, initialised lazily with `??=` so the cache
13
+ * (and its disk IO) is only created on the first getCache() call.
14
+ */
8
15
  let cache;
16
+ /**
17
+ * 建立檔案後盾的 LRU 快取 (File-backed LRU Cache) 實例。
18
+ *
19
+ * Creates the file-backed LRU cache instance.
20
+ *
21
+ * @param options 查詢選項,僅取用其中的 cacheAgentOptions / Query options; only cacheAgentOptions is used
22
+ * @returns 新的快取實例 / A fresh cache instance
23
+ */
9
24
  function initCache(options) {
10
25
  let id = '@yarn-tool/pkg-version-query';
26
+ /**
27
+ * 快取目錄依序偏好 yarn 快取、npm 快取、系統暫存目錄,最後才退回 node_modules;
28
+ * 這樣可與套件管理器共用既有快取位置,也避免在唯讀的 node_modules 下寫檔。
29
+ *
30
+ * The cache dir prefers the yarn cache, then npm cache, then OS temp, and only
31
+ * falls back to node_modules; this reuses package-manager cache locations and
32
+ * avoids writing into a potentially read-only node_modules.
33
+ */
11
34
  let cwd = (0, cache_path_1.getCachePath)(id, {
12
35
  fnOrder: [
13
36
  cache_path_1.findYarnCachePath,
@@ -17,6 +40,13 @@ function initCache(options) {
17
40
  ],
18
41
  });
19
42
  let { cacheAgentOptions } = (options !== null && options !== void 0 ? options : (options = {}));
43
+ /**
44
+ * 使用展開運算子合併:呼叫端的設定優先,但 cacheName / autoCreate / cwd
45
+ * 由本函式決定,避免使用者誤覆寫成指向別的快取檔。
46
+ *
47
+ * Spread-merge keeps caller settings first while cacheName / autoCreate / cwd stay
48
+ * under this function's control, so callers cannot accidentally point at another cache file.
49
+ */
20
50
  cacheAgentOptions = {
21
51
  // max: 1000,
22
52
  // maxAge: 5 * 60 * 1000,
@@ -25,15 +55,41 @@ function initCache(options) {
25
55
  autoCreate: true,
26
56
  cwd,
27
57
  };
58
+ /**
59
+ * 下限保護:max 太小(或未設定)會使快取幾乎無效、每次查詢都打 registry,
60
+ * 因此強制提升到 1000。
61
+ *
62
+ * Floor guard: a tiny or unset max would make the cache useless and hammer the
63
+ * registry on every query, so it is raised to 1000.
64
+ */
28
65
  if (!cacheAgentOptions.max || cacheAgentOptions.max <= 100) {
29
66
  cacheAgentOptions.max = 1000;
30
67
  }
68
+ /**
69
+ * 下限保護:maxAge 太短(或未設定)會讓版本資料幾乎立刻過期,
70
+ * 因此強制至少保留 10 分鐘。
71
+ *
72
+ * Floor guard: a too-short or unset maxAge would expire version data almost
73
+ * immediately, so it is kept at 10 minutes at minimum.
74
+ */
31
75
  if (!cacheAgentOptions.maxAge || cacheAgentOptions.maxAge <= 60 * 1000) {
32
76
  cacheAgentOptions.maxAge = 10 * 60 * 1000;
33
77
  }
34
78
  const cache = new lru_cache_fs2_1.default(cacheAgentOptions);
35
79
  return cache;
36
80
  }
81
+ /**
82
+ * 取得快取實例:優先使用呼叫端自帶的 cacheAgent,
83
+ * 否則以 `??=` 惰性建立並重複使用同一個單例,
84
+ * 讓多處查詢共享同一份磁碟快取而不必各自初始化。
85
+ *
86
+ * Returns the cache instance: a caller-supplied cacheAgent wins, otherwise a
87
+ * module-level singleton is created lazily via `??=` so scattered queries share
88
+ * one disk-backed cache instead of each initialising their own.
89
+ *
90
+ * @param options 查詢選項,可攜帶 cacheAgent / Query options; may carry a custom cacheAgent
91
+ * @returns 快取實例 / The cache instance
92
+ */
37
93
  function getCache(options) {
38
94
  var _a;
39
95
  return (_a = options === null || options === void 0 ? void 0 : options.cacheAgent) !== null && _a !== void 0 ? _a : (cache !== null && cache !== void 0 ? cache : (cache = initCache(options)));
@@ -1 +1 @@
1
- {"version":3,"file":"cacheAgent.js","sourceRoot":"","sources":["cacheAgent.ts"],"names":[],"mappings":";;AAcA,8BAqCC;AAED,4BAGC;;AAxDD,0EAA0D;AAC1D,2CAOoB;AAIpB,IAAI,KAA0C,CAAC;AAE/C,SAAgB,SAAS,CAAC,OAAuC;IAEhE,IAAI,EAAE,GAAG,8BAA8B,CAAC;IAExC,IAAI,GAAG,GAAG,IAAA,yBAAY,EAAC,EAAE,EAAE;QAC1B,OAAO,EAAE;YACR,8BAAiB;YACjB,6BAAgB;YAChB,2BAAc;YACd,8BAAiB;SACjB;KACD,CAAC,CAAC;IAEH,IAAI,EAAE,iBAAiB,EAAE,GAAG,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,IAAP,OAAO,GAAK,EAAE,EAAC,CAAC;IAE7C,iBAAiB,GAAG;QACrB,cAAc;QACd,0BAA0B;QACxB,GAAG,iBAAiB;QACpB,SAAS,EAAE,IAAA,0BAAa,EAAC,EAAE,EAAE,IAAI,CAAC;QAClC,UAAU,EAAE,IAAI;QAChB,GAAG;KACH,CAAA;IAED,IAAI,CAAC,iBAAiB,CAAC,GAAG,IAAI,iBAAiB,CAAC,GAAG,IAAI,GAAG,EAC1D,CAAC;QACA,iBAAiB,CAAC,GAAG,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC,iBAAiB,CAAC,MAAM,IAAI,iBAAiB,CAAC,MAAM,IAAI,EAAE,GAAG,IAAI,EACtE,CAAC;QACA,iBAAiB,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,uBAAK,CAA+B,iBAAiB,CAAC,CAAC;IAEzE,OAAO,KAAK,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,OAAuC;;IAE/D,OAAO,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,mCAAI,CAAC,KAAK,aAAL,KAAK,cAAL,KAAK,IAAL,KAAK,GAAK,SAAS,CAAC,OAAO,CAAC,EAAC,CAAC;AAC9D,CAAC","sourcesContent":["import Cache, { IOptionsLRUCacheFS } from 'lru-cache-fs2';\nimport {\n\tnormalizeName,\n\tgetCachePath,\n\tfindPkgModulePath,\n\tfindYarnCachePath,\n\tfindNpmCachePath,\n\tfindOSTempPath,\n} from 'cache-path';\nimport { ICachedVersionResult, IOptionsQueryVersion } from './types';\nimport { Options } from 'package-json';\n\nlet cache: Cache<string, ICachedVersionResult>;\n\nexport function initCache(options?: IOptionsQueryVersion<Options>)\n{\n\tlet id = '@yarn-tool/pkg-version-query';\n\n\tlet cwd = getCachePath(id, {\n\t\tfnOrder: [\n\t\t\tfindYarnCachePath,\n\t\t\tfindNpmCachePath,\n\t\t\tfindOSTempPath,\n\t\t\tfindPkgModulePath,\n\t\t],\n\t});\n\n\tlet { cacheAgentOptions } = (options ??= {});\n\n\tcacheAgentOptions = {\n//\t\tmax: 1000,\n//\t\tmaxAge: 5 * 60 * 1000,\n\t\t...cacheAgentOptions,\n\t\tcacheName: normalizeName(id, true),\n\t\tautoCreate: true,\n\t\tcwd,\n\t}\n\n\tif (!cacheAgentOptions.max || cacheAgentOptions.max <= 100)\n\t{\n\t\tcacheAgentOptions.max = 1000;\n\t}\n\n\tif (!cacheAgentOptions.maxAge || cacheAgentOptions.maxAge <= 60 * 1000)\n\t{\n\t\tcacheAgentOptions.maxAge = 10 * 60 * 1000;\n\t}\n\n\tconst cache = new Cache<string, ICachedVersionResult>(cacheAgentOptions);\n\n\treturn cache;\n}\n\nexport function getCache(options?: IOptionsQueryVersion<Options>)\n{\n\treturn options?.cacheAgent ?? (cache ??= initCache(options));\n}\n"]}
1
+ {"version":3,"file":"cacheAgent.js","sourceRoot":"","sources":["cacheAgent.ts"],"names":[],"mappings":";;AA6BA,8BAkEC;AAcD,4BAGC;;AAhHD,0EAA0D;AAC1D,2CAOoB;AAIpB;;;;;;GAMG;AACH,IAAI,KAA0C,CAAC;AAE/C;;;;;;;GAOG;AACH,SAAgB,SAAS,CAAC,OAAuC;IAEhE,IAAI,EAAE,GAAG,8BAA8B,CAAC;IAExC;;;;;;;OAOG;IACH,IAAI,GAAG,GAAG,IAAA,yBAAY,EAAC,EAAE,EAAE;QAC1B,OAAO,EAAE;YACR,8BAAiB;YACjB,6BAAgB;YAChB,2BAAc;YACd,8BAAiB;SACjB;KACD,CAAC,CAAC;IAEH,IAAI,EAAE,iBAAiB,EAAE,GAAG,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,IAAP,OAAO,GAAK,EAAE,EAAC,CAAC;IAE7C;;;;;;OAMG;IACH,iBAAiB,GAAG;QACrB,cAAc;QACd,0BAA0B;QACxB,GAAG,iBAAiB;QACpB,SAAS,EAAE,IAAA,0BAAa,EAAC,EAAE,EAAE,IAAI,CAAC;QAClC,UAAU,EAAE,IAAI;QAChB,GAAG;KACH,CAAA;IAED;;;;;;OAMG;IACH,IAAI,CAAC,iBAAiB,CAAC,GAAG,IAAI,iBAAiB,CAAC,GAAG,IAAI,GAAG,EAC1D,CAAC;QACA,iBAAiB,CAAC,GAAG,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,iBAAiB,CAAC,MAAM,IAAI,iBAAiB,CAAC,MAAM,IAAI,EAAE,GAAG,IAAI,EACtE,CAAC;QACA,iBAAiB,CAAC,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,uBAAK,CAA+B,iBAAiB,CAAC,CAAC;IAEzE,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,QAAQ,CAAC,OAAuC;;IAE/D,OAAO,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,UAAU,mCAAI,CAAC,KAAK,aAAL,KAAK,cAAL,KAAK,IAAL,KAAK,GAAK,SAAS,CAAC,OAAO,CAAC,EAAC,CAAC;AAC9D,CAAC","sourcesContent":["import Cache, { IOptionsLRUCacheFS } from 'lru-cache-fs2';\nimport {\n\tnormalizeName,\n\tgetCachePath,\n\tfindPkgModulePath,\n\tfindYarnCachePath,\n\tfindNpmCachePath,\n\tfindOSTempPath,\n} from 'cache-path';\nimport { ICachedVersionResult, IOptionsQueryVersion } from './types';\nimport { Options } from 'package-json';\n\n/**\n * 模組層級的快取單例 (Module-level Cache Singleton);\n * 以 `??=` 延後初始化,確保只有第一次 getCache() 才會建立快取並產生磁碟 IO。\n *\n * Module-level cache singleton, initialised lazily with `??=` so the cache\n * (and its disk IO) is only created on the first getCache() call.\n */\nlet cache: Cache<string, ICachedVersionResult>;\n\n/**\n * 建立檔案後盾的 LRU 快取 (File-backed LRU Cache) 實例。\n *\n * Creates the file-backed LRU cache instance.\n *\n * @param options 查詢選項,僅取用其中的 cacheAgentOptions / Query options; only cacheAgentOptions is used\n * @returns 新的快取實例 / A fresh cache instance\n */\nexport function initCache(options?: IOptionsQueryVersion<Options>)\n{\n\tlet id = '@yarn-tool/pkg-version-query';\n\n\t/**\n\t * 快取目錄依序偏好 yarn 快取、npm 快取、系統暫存目錄,最後才退回 node_modules;\n\t * 這樣可與套件管理器共用既有快取位置,也避免在唯讀的 node_modules 下寫檔。\n\t *\n\t * The cache dir prefers the yarn cache, then npm cache, then OS temp, and only\n\t * falls back to node_modules; this reuses package-manager cache locations and\n\t * avoids writing into a potentially read-only node_modules.\n\t */\n\tlet cwd = getCachePath(id, {\n\t\tfnOrder: [\n\t\t\tfindYarnCachePath,\n\t\t\tfindNpmCachePath,\n\t\t\tfindOSTempPath,\n\t\t\tfindPkgModulePath,\n\t\t],\n\t});\n\n\tlet { cacheAgentOptions } = (options ??= {});\n\n\t/**\n\t * 使用展開運算子合併:呼叫端的設定優先,但 cacheName / autoCreate / cwd\n\t * 由本函式決定,避免使用者誤覆寫成指向別的快取檔。\n\t *\n\t * Spread-merge keeps caller settings first while cacheName / autoCreate / cwd stay\n\t * under this function's control, so callers cannot accidentally point at another cache file.\n\t */\n\tcacheAgentOptions = {\n//\t\tmax: 1000,\n//\t\tmaxAge: 5 * 60 * 1000,\n\t\t...cacheAgentOptions,\n\t\tcacheName: normalizeName(id, true),\n\t\tautoCreate: true,\n\t\tcwd,\n\t}\n\n\t/**\n\t * 下限保護:max 太小(或未設定)會使快取幾乎無效、每次查詢都打 registry,\n\t * 因此強制提升到 1000。\n\t *\n\t * Floor guard: a tiny or unset max would make the cache useless and hammer the\n\t * registry on every query, so it is raised to 1000.\n\t */\n\tif (!cacheAgentOptions.max || cacheAgentOptions.max <= 100)\n\t{\n\t\tcacheAgentOptions.max = 1000;\n\t}\n\n\t/**\n\t * 下限保護:maxAge 太短(或未設定)會讓版本資料幾乎立刻過期,\n\t * 因此強制至少保留 10 分鐘。\n\t *\n\t * Floor guard: a too-short or unset maxAge would expire version data almost\n\t * immediately, so it is kept at 10 minutes at minimum.\n\t */\n\tif (!cacheAgentOptions.maxAge || cacheAgentOptions.maxAge <= 60 * 1000)\n\t{\n\t\tcacheAgentOptions.maxAge = 10 * 60 * 1000;\n\t}\n\n\tconst cache = new Cache<string, ICachedVersionResult>(cacheAgentOptions);\n\n\treturn cache;\n}\n\n/**\n * 取得快取實例:優先使用呼叫端自帶的 cacheAgent,\n * 否則以 `??=` 惰性建立並重複使用同一個單例,\n * 讓多處查詢共享同一份磁碟快取而不必各自初始化。\n *\n * Returns the cache instance: a caller-supplied cacheAgent wins, otherwise a\n * module-level singleton is created lazily via `??=` so scattered queries share\n * one disk-backed cache instead of each initialising their own.\n *\n * @param options 查詢選項,可攜帶 cacheAgent / Query options; may carry a custom cacheAgent\n * @returns 快取實例 / The cache instance\n */\nexport function getCache(options?: IOptionsQueryVersion<Options>)\n{\n\treturn options?.cacheAgent ?? (cache ??= initCache(options));\n}\n"]}
package/lib/core.js CHANGED
@@ -13,9 +13,24 @@ const tslib_1 = require("tslib");
13
13
  const package_json_1 = tslib_1.__importDefault(require("package-json"));
14
14
  const bluebird_1 = tslib_1.__importDefault(require("bluebird"));
15
15
  function _queryVersion(packageName, options) {
16
+ /**
17
+ * 選項允許省略:交給 package-json 使用其預設值,
18
+ * 避免每個呼叫端都要自行組出空物件。
19
+ *
20
+ * Options are optional: an empty object lets package-json apply its own defaults,
21
+ * so callers do not have to build one themselves.
22
+ */
16
23
  options !== null && options !== void 0 ? options : (options = {});
17
24
  return bluebird_1.default.resolve((0, package_json_1.default)(packageName, options))
18
25
  .catch(e => {
26
+ /**
27
+ * notThrowError 是給「寧可拿不到也不要中斷流程」的批次查詢用的;
28
+ * 回傳 undefined 而非吞掉後回傳舊值,讓呼叫端能明確區分失敗與命中。
29
+ *
30
+ * notThrowError serves batch queries that prefer no result over a crash;
31
+ * returning undefined (instead of some stale value) lets callers
32
+ * distinguish failure from a real hit.
33
+ */
19
34
  if (options.notThrowError) {
20
35
  return;
21
36
  }
package/lib/core.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"core.js","sourceRoot":"","sources":["core.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAgCH,sCAeC;;AA7CD,wEAMsB;AACtB,gEAAgC;AAuBhC,SAAgB,aAAa,CAAC,WAAmB,EAAE,OAAuC;IAEzF,OAAO,aAAP,OAAO,cAAP,OAAO,IAAP,OAAO,GAAK,EAAE,EAAC;IAEf,OAAO,kBAAQ,CAAC,OAAO,CAAC,IAAA,sBAAY,EAAC,WAAW,EAAE,OAAO,CAAC,CAAC;SACzD,KAAK,CAAC,CAAC,CAAC,EAAE;QAEV,IAAI,OAAO,CAAC,aAAa,EACzB,CAAC;YACA,OAAM;QACP,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACzB,CAAC,CAAQ,CACR;AACH,CAAC","sourcesContent":["/**\n * Core version query function using package-json.\n * 使用 package-json 的核心版本查詢函數。\n *\n * @module core\n *\n * 提供底層的 npm registry 查詢功能,封裝 package-json 模組。\n */\n\nimport _packageJson, {\n\tOptions,\n\tAbbreviatedVersion,\n\tAbbreviatedMetadata,\n\tFullMetadataOptions,\n\tFullMetadata,\n} from 'package-json';\nimport Bluebird from 'bluebird';\nimport { IOptionsQueryVersion } from './types';\n\n/**\n * Query package information from npm registry.\n * 從 npm registry 查詢套件資訊。\n *\n * @param packageName - Package name to query / 要查詢的套件名稱\n * @param options - Query options / 查詢選項\n * @returns Promise resolving to package metadata / 回傳套件元資料的 Promise\n */\nexport function _queryVersion(packageName: string,\n\toptions: IOptionsQueryVersion<FullMetadataOptions>,\n): Bluebird<FullMetadata>;\nexport function _queryVersion(packageName: string,\n\toptions: Omit<Options, 'allVersions' | 'version'> & {\n\t\tallVersions?: false,\n\t\tversion: string,\n\t},\n): Bluebird<AbbreviatedVersion>\nexport function _queryVersion(packageName: string,\n\toptions?: IOptionsQueryVersion<Options>,\n): Bluebird<AbbreviatedMetadata>\nexport function _queryVersion(packageName: string, options?: IOptionsQueryVersion<Options>)\n{\n\toptions ??= {};\n\n\treturn Bluebird.resolve(_packageJson(packageName, options))\n\t\t.catch(e =>\n\t\t{\n\t\t\tif (options.notThrowError)\n\t\t\t{\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\treturn Promise.reject(e)\n\t\t}) as any\n\t\t;\n}\n"]}
1
+ {"version":3,"file":"core.js","sourceRoot":"","sources":["core.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAgCH,sCA8BC;;AA5DD,wEAMsB;AACtB,gEAAgC;AAuBhC,SAAgB,aAAa,CAAC,WAAmB,EAAE,OAAuC;IAEzF;;;;;;OAMG;IACH,OAAO,aAAP,OAAO,cAAP,OAAO,IAAP,OAAO,GAAK,EAAE,EAAC;IAEf,OAAO,kBAAQ,CAAC,OAAO,CAAC,IAAA,sBAAY,EAAC,WAAW,EAAE,OAAO,CAAC,CAAC;SACzD,KAAK,CAAC,CAAC,CAAC,EAAE;QAEV;;;;;;;WAOG;QACH,IAAI,OAAO,CAAC,aAAa,EACzB,CAAC;YACA,OAAM;QACP,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACzB,CAAC,CAAQ,CACR;AACH,CAAC","sourcesContent":["/**\n * Core version query function using package-json.\n * 使用 package-json 的核心版本查詢函數。\n *\n * @module core\n *\n * 提供底層的 npm registry 查詢功能,封裝 package-json 模組。\n */\n\nimport _packageJson, {\n\tOptions,\n\tAbbreviatedVersion,\n\tAbbreviatedMetadata,\n\tFullMetadataOptions,\n\tFullMetadata,\n} from 'package-json';\nimport Bluebird from 'bluebird';\nimport { IOptionsQueryVersion } from './types';\n\n/**\n * Query package information from npm registry.\n * 從 npm registry 查詢套件資訊。\n *\n * @param packageName - Package name to query / 要查詢的套件名稱\n * @param options - Query options / 查詢選項\n * @returns Promise resolving to package metadata / 回傳套件元資料的 Promise\n */\nexport function _queryVersion(packageName: string,\n\toptions: IOptionsQueryVersion<FullMetadataOptions>,\n): Bluebird<FullMetadata>;\nexport function _queryVersion(packageName: string,\n\toptions: Omit<Options, 'allVersions' | 'version'> & {\n\t\tallVersions?: false,\n\t\tversion: string,\n\t},\n): Bluebird<AbbreviatedVersion>\nexport function _queryVersion(packageName: string,\n\toptions?: IOptionsQueryVersion<Options>,\n): Bluebird<AbbreviatedMetadata>\nexport function _queryVersion(packageName: string, options?: IOptionsQueryVersion<Options>)\n{\n\t/**\n\t * 選項允許省略:交給 package-json 使用其預設值,\n\t * 避免每個呼叫端都要自行組出空物件。\n\t *\n\t * Options are optional: an empty object lets package-json apply its own defaults,\n\t * so callers do not have to build one themselves.\n\t */\n\toptions ??= {};\n\n\treturn Bluebird.resolve(_packageJson(packageName, options))\n\t\t.catch(e =>\n\t\t{\n\t\t\t/**\n\t\t\t * notThrowError 是給「寧可拿不到也不要中斷流程」的批次查詢用的;\n\t\t\t * 回傳 undefined 而非吞掉後回傳舊值,讓呼叫端能明確區分失敗與命中。\n\t\t\t *\n\t\t\t * notThrowError serves batch queries that prefer no result over a crash;\n\t\t\t * returning undefined (instead of some stale value) lets callers\n\t\t\t * distinguish failure from a real hit.\n\t\t\t */\n\t\t\tif (options.notThrowError)\n\t\t\t{\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\treturn Promise.reject(e)\n\t\t}) as any\n\t\t;\n}\n"]}
@@ -1 +1,14 @@
1
+ /**
2
+ * 產生快取鍵 (Cache Key):固定使用 `name@targetVersion` 格式,
3
+ * 讓「同一個套件 + 同一個版本範圍」必定對應到同一筆快取;
4
+ * 格式刻意保持簡單,因為鍵值會被寫入磁碟快取,日後變更格式會使舊快取全部失效。
5
+ *
6
+ * Builds the cache key as `name@targetVersion` so the same package + version range
7
+ * always maps to the same entry. The format is kept simple on purpose: keys are
8
+ * persisted to disk, so changing the shape later would invalidate every old entry.
9
+ *
10
+ * @param name 套件名稱 / Package name
11
+ * @param targetVersion 目標版本或範圍 / Target version or range
12
+ * @returns 快取鍵字串 / The cache key string
13
+ */
1
14
  export declare function _createCacheKey(name: string, targetVersion: string): string;
@@ -1,6 +1,19 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports._createCacheKey = _createCacheKey;
4
+ /**
5
+ * 產生快取鍵 (Cache Key):固定使用 `name@targetVersion` 格式,
6
+ * 讓「同一個套件 + 同一個版本範圍」必定對應到同一筆快取;
7
+ * 格式刻意保持簡單,因為鍵值會被寫入磁碟快取,日後變更格式會使舊快取全部失效。
8
+ *
9
+ * Builds the cache key as `name@targetVersion` so the same package + version range
10
+ * always maps to the same entry. The format is kept simple on purpose: keys are
11
+ * persisted to disk, so changing the shape later would invalidate every old entry.
12
+ *
13
+ * @param name 套件名稱 / Package name
14
+ * @param targetVersion 目標版本或範圍 / Target version or range
15
+ * @returns 快取鍵字串 / The cache key string
16
+ */
4
17
  function _createCacheKey(name, targetVersion) {
5
18
  return `${name}@${targetVersion}`;
6
19
  }
@@ -1 +1 @@
1
- {"version":3,"file":"createCacheKey.js","sourceRoot":"","sources":["createCacheKey.ts"],"names":[],"mappings":";;AACA,0CAGC;AAHD,SAAgB,eAAe,CAAC,IAAY,EAAE,aAAqB;IAElE,OAAO,GAAG,IAAI,IAAI,aAAa,EAAE,CAAA;AAClC,CAAC","sourcesContent":["\nexport function _createCacheKey(name: string, targetVersion: string)\n{\n\treturn `${name}@${targetVersion}`\n}\n"]}
1
+ {"version":3,"file":"createCacheKey.js","sourceRoot":"","sources":["createCacheKey.ts"],"names":[],"mappings":";;AAcA,0CAGC;AAhBD;;;;;;;;;;;;GAYG;AACH,SAAgB,eAAe,CAAC,IAAY,EAAE,aAAqB;IAElE,OAAO,GAAG,IAAI,IAAI,aAAa,EAAE,CAAA;AAClC,CAAC","sourcesContent":["\n/**\n * 產生快取鍵 (Cache Key):固定使用 `name@targetVersion` 格式,\n * 讓「同一個套件 + 同一個版本範圍」必定對應到同一筆快取;\n * 格式刻意保持簡單,因為鍵值會被寫入磁碟快取,日後變更格式會使舊快取全部失效。\n *\n * Builds the cache key as `name@targetVersion` so the same package + version range\n * always maps to the same entry. The format is kept simple on purpose: keys are\n * persisted to disk, so changing the shape later would invalidate every old entry.\n *\n * @param name 套件名稱 / Package name\n * @param targetVersion 目標版本或範圍 / Target version or range\n * @returns 快取鍵字串 / The cache key string\n */\nexport function _createCacheKey(name: string, targetVersion: string)\n{\n\treturn `${name}@${targetVersion}`\n}\n"]}
@@ -32,5 +32,17 @@ import { IOptionsQueryVersion } from './types';
32
32
  * ```
33
33
  */
34
34
  export declare function queryVersionWithCache(name: string, targetVersion?: string, options?: IOptionsQueryVersion<Options>): Bluebird<string>;
35
+ /**
36
+ * 查詢版本的核心流程:registry 查詢 → 失敗時正規化版本重試 → 結果回寫快取。
37
+ *
38
+ * Core query flow: registry lookup → normalise the version and retry on failure →
39
+ * write the outcome back to the cache.
40
+ *
41
+ * @param name 套件名稱 / Package name
42
+ * @param targetVersion 目標版本或範圍,預設 latest / Target version or range, defaults to latest
43
+ * @param save 是否將結果寫回快取;正規化後的遞迴重試傳 false / Whether to write the outcome back to the cache; pass false for the normalised retry
44
+ * @param options 查詢與快取選項 / Query and cache options
45
+ * @returns 解析出的版本字串 / The resolved version string
46
+ */
35
47
  export declare function queryVersion(name: string, targetVersion?: string, save?: boolean, options?: IOptionsQueryVersion<Options>): Bluebird<string>;
36
48
  export default queryVersionWithCache;
@@ -45,14 +45,40 @@ function queryVersionWithCache(name, targetVersion = 'latest', options) {
45
45
  return bluebird_1.default.resolve((0, queryVersionCacheRaw_1.queryVersionCacheRaw)(name, targetVersion, options))
46
46
  .then(data => {
47
47
  var _a;
48
+ /**
49
+ * 快取存有先前的失敗紀錄時直接重拋:
50
+ * 同一組 name/version 短時間內重試通常仍會失敗,
51
+ * 再打一次 registry 只是白白拖慢流程。
52
+ *
53
+ * A cached failure is rethrown immediately: retrying the same name/version
54
+ * right away would almost certainly fail again, so another registry call
55
+ * would only slow things down.
56
+ */
48
57
  if (data === null || data === void 0 ? void 0 : data.error) {
49
58
  return Promise.reject(data.error);
50
59
  }
60
+ /**
61
+ * 快取命中成功結果時直接回傳,略過網路請求。
62
+ *
63
+ * A cached success is returned as-is, skipping the network request.
64
+ */
51
65
  else if (data === null || data === void 0 ? void 0 : data.result) {
52
66
  return data.result;
53
67
  }
68
+ /**
69
+ * 未命中(或快取列只有 version 欄位)時才真的發起查詢。
70
+ *
71
+ * Only a real query happens on a miss (or when the entry only carries `version`).
72
+ */
54
73
  return queryVersion(name, (_a = data === null || data === void 0 ? void 0 : data.version) !== null && _a !== void 0 ? _a : targetVersion, true, options)
55
74
  .catch(e => {
75
+ /**
76
+ * 查詢失敗時的後備 (Fallback):若快取中已有成功結果則改採快取值,
77
+ * 只有完全沒有可用結果時才把錯誤拋回給呼叫端。
78
+ *
79
+ * Fallback on failure: prefer an already-cached success when one exists,
80
+ * and only rethrow to the caller when no usable result is available.
81
+ */
56
82
  if (data === null || data === void 0 ? void 0 : data.result) {
57
83
  return data.result;
58
84
  }
@@ -60,7 +86,26 @@ function queryVersionWithCache(name, targetVersion = 'latest', options) {
60
86
  });
61
87
  });
62
88
  }
89
+ /**
90
+ * 查詢版本的核心流程:registry 查詢 → 失敗時正規化版本重試 → 結果回寫快取。
91
+ *
92
+ * Core query flow: registry lookup → normalise the version and retry on failure →
93
+ * write the outcome back to the cache.
94
+ *
95
+ * @param name 套件名稱 / Package name
96
+ * @param targetVersion 目標版本或範圍,預設 latest / Target version or range, defaults to latest
97
+ * @param save 是否將結果寫回快取;正規化後的遞迴重試傳 false / Whether to write the outcome back to the cache; pass false for the normalised retry
98
+ * @param options 查詢與快取選項 / Query and cache options
99
+ * @returns 解析出的版本字串 / The resolved version string
100
+ */
63
101
  function queryVersion(name, targetVersion = 'latest', save = true, options) {
102
+ /**
103
+ * ??= 補齊預設版本;快取鍵以補齊後的版本建立,
104
+ * 讓「省略 targetVersion」與「顯式傳入 'latest'」共用同一筆快取。
105
+ *
106
+ * ??= fills in the default; the cache key is built from the normalised version so
107
+ * "omit targetVersion" and an explicit 'latest' share the same cache entry.
108
+ */
64
109
  let version = targetVersion !== null && targetVersion !== void 0 ? targetVersion : (targetVersion = 'latest');
65
110
  let key = (0, createCacheKey_1._createCacheKey)(name, targetVersion);
66
111
  return (0, core_1._queryVersion)(name, {
@@ -70,21 +115,64 @@ function queryVersion(name, targetVersion = 'latest', save = true, options) {
70
115
  return result.version;
71
116
  })
72
117
  .catch(package_json_1.VersionNotFoundError, async (e) => {
118
+ /**
119
+ * bool 表示「版本是否已被正規化」;
120
+ * 只有真的改寫過才值得用新版本重試一次。
121
+ *
122
+ * `bool` tracks whether the version was actually normalised;
123
+ * only a rewritten version is worth one retry.
124
+ */
73
125
  let bool = true;
126
+ /**
127
+ * npm: 別名協定 (Alias Protocol) 的字串 registry 無法直接解析,
128
+ * 剝掉前綴後以剩餘規格重試(例如 `npm:foo@1.0.0` → `foo@1.0.0`)。
129
+ *
130
+ * The npm: alias protocol is not parseable by the registry as-is,
131
+ * so the prefix is stripped and the remainder retried.
132
+ */
74
133
  if (version.startsWith('npm:')) {
75
134
  version = version.replace(/^npm:/, '');
76
135
  bool = false;
77
136
  }
137
+ /**
138
+ * 版本範圍中的 `&` 與空白(常見於套件管理器產生的範圍)需先正規化,
139
+ * 否則 registry 端的 semver 解析會失敗。
140
+ *
141
+ * `&` and whitespace inside a range (common in package-manager output)
142
+ * must be normalised first, otherwise semver parsing fails upstream.
143
+ */
78
144
  if (const_1.reAmpersandAndSpaces.test(version)) {
79
145
  version = (0, handleAmpersandAndSpaces_1.handleAmpersandAndSpaces)(version);
80
146
  bool = false;
81
147
  }
148
+ /**
149
+ * 兩種正規化都沒套用時,重試只會得到相同的錯誤;
150
+ * 直接重拋原錯誤,避免以相同輸入無限遞迴。
151
+ *
152
+ * When neither normalisation applied, a retry would hit the same error;
153
+ * rethrow immediately to avoid infinite recursion on identical input.
154
+ */
82
155
  if (bool) {
83
156
  return Promise.reject(e);
84
157
  }
158
+ /**
159
+ * 以正規化後的版本重試;save=false 是為了避免遞迴呼叫重複寫入快取,
160
+ * 外層的 tap / tapCatch 仍會以原始 key 記錄最終結果。
161
+ *
162
+ * Retry with the normalised version; save=false prevents the recursive call
163
+ * from double-writing the cache — the outer tap / tapCatch still records
164
+ * the final outcome under the original key.
165
+ */
85
166
  return queryVersion(name, version, false, options);
86
167
  })
87
168
  .tapCatch(package_json_1.VersionNotFoundError, package_json_1.PackageNotFoundError, (error) => {
169
+ /**
170
+ * 負面快取 (Negative Cache):把「版本/套件不存在」也記下來,
171
+ * 避免每次呼叫都重複打 registry 查詢一個確定失敗的目標。
172
+ *
173
+ * Negative cache: remember "version/package not found" so repeated calls
174
+ * do not re-query a target that is known to fail.
175
+ */
88
176
  save && (0, cacheAgent_1.getCache)(options).set(key, {
89
177
  key,
90
178
  name,
@@ -93,6 +181,11 @@ function queryVersion(name, targetVersion = 'latest', save = true, options) {
93
181
  });
94
182
  })
95
183
  .tap(result => {
184
+ /**
185
+ * 成功結果寫回快取,供後續查詢直接命中。
186
+ *
187
+ * Write the successful result back so later lookups hit the cache.
188
+ */
96
189
  save && (0, cacheAgent_1.getCache)(options).set(key, {
97
190
  key,
98
191
  name,
@@ -1 +1 @@
1
- {"version":3,"file":"queryVersion.js","sourceRoot":"","sources":["queryVersion.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Query package versions with cache support.\n * 查詢套件版本並支援快取機制。\n *\n * @module queryVersion\n *\n * 主要功能:\n * - 從 npm registry 查詢套件版本\n * - 支援 LRU 快取,減少重複查詢\n * - 處理版本範圍語法 (如 ^, ~, npm: 協議)\n * - 錯誤處理與快取錯誤結果\n */\n\nimport { PackageNotFoundError, VersionNotFoundError, Options } from 'package-json';\nimport Bluebird from 'bluebird';\nimport { getCache } from './cacheAgent';\nimport { _createCacheKey } from './createCacheKey';\nimport { _queryVersion } from './core';\nimport { queryVersionCacheRaw } from './queryVersionCacheRaw';\nimport { IOptionsQueryVersion } from './types';\nimport { handleAmpersandAndSpaces } from '@lazy-node/semver-ampersand/lib/handleAmpersandAndSpaces';\nimport { reAmpersandAndSpaces } from '@lazy-node/semver-ampersand/lib/const';\n\n/**\n * Query package version with LRU cache.\n * 使用 LRU 快取查詢套件版本。\n *\n * @param name - Package name / 套件名稱\n * @param targetVersion - Target version or range (default: 'latest') / 目標版本或範圍\n * @param options - Query options / 查詢選項\n * @returns Promise resolving to version string / 回傳版本字串的 Promise\n *\n * @example\n * ```ts\n * const version = await queryVersionWithCache('lodash');\n * // => '4.17.21'\n *\n * const version = await queryVersionWithCache('typescript', '^4.0.0');\n * // => '4.9.5'\n * ```\n */\nexport function queryVersionWithCache(name: string, targetVersion: string = 'latest', options?: IOptionsQueryVersion<Options>): Bluebird<string>\n{\n\treturn Bluebird.resolve(queryVersionCacheRaw(name, targetVersion, options))\n\t\t.then(data =>\n\t\t{\n\t\t\tif (data?.error)\n\t\t\t{\n\t\t\t\treturn Promise.reject(data.error)\n\t\t\t}\n\t\t\telse if (data?.result)\n\t\t\t{\n\t\t\t\treturn data.result\n\t\t\t}\n\n\t\t\treturn queryVersion(name, data?.version ?? targetVersion, true,options)\n\t\t\t\t.catch(e => {\n\t\t\t\t\tif (data?.result)\n\t\t\t\t\t{\n\t\t\t\t\t\treturn data.result\n\t\t\t\t\t}\n\n\t\t\t\t\treturn Promise.reject(e)\n\t\t\t\t})\n\t\t})\n}\n\nexport function queryVersion(name: string, targetVersion: string = 'latest', save: boolean = true, options?: IOptionsQueryVersion<Options>): Bluebird<string>\n{\n\tlet version = targetVersion ??= 'latest';\n\tlet key = _createCacheKey(name, targetVersion);\n\n\treturn _queryVersion(name, {\n\t\tversion,\n\t})\n\t\t.then((result) =>\n\t\t{\n\t\t\treturn result.version\n\t\t})\n\t\t.catch(VersionNotFoundError, async (e) =>\n\t\t{\n\t\t\tlet bool = true;\n\n\t\t\tif (version.startsWith('npm:'))\n\t\t\t{\n\t\t\t\tversion = version.replace(/^npm:/, '')\n\n\t\t\t\tbool = false\n\t\t\t}\n\n\t\t\tif (reAmpersandAndSpaces.test(version))\n\t\t\t{\n\t\t\t\tversion = handleAmpersandAndSpaces(version)\n\n\t\t\t\tbool = false\n\t\t\t}\n\n\t\t\tif (bool)\n\t\t\t{\n\t\t\t\treturn Promise.reject(e)\n\t\t\t}\n\n\t\t\treturn queryVersion(name, version, false,options)\n\t\t})\n\t\t.tapCatch(VersionNotFoundError, PackageNotFoundError, (error) =>\n\t\t{\n\t\t\tsave && getCache(options).set(key, {\n\t\t\t\tkey,\n\t\t\t\tname,\n\t\t\t\tversion,\n\t\t\t\terror,\n\t\t\t});\n\t\t})\n\t\t.tap(result =>\n\t\t{\n\t\t\tsave && getCache(options).set(key, {\n\t\t\t\tkey,\n\t\t\t\tname,\n\t\t\t\tversion,\n\t\t\t\tresult,\n\t\t\t});\n\t\t})\n\t\t;\n}\n\nexport default queryVersionWithCache\n"]}
1
+ {"version":3,"file":"queryVersion.js","sourceRoot":"","sources":["queryVersion.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Query package versions with cache support.\n * 查詢套件版本並支援快取機制。\n *\n * @module queryVersion\n *\n * 主要功能:\n * - 從 npm registry 查詢套件版本\n * - 支援 LRU 快取,減少重複查詢\n * - 處理版本範圍語法 (如 ^, ~, npm: 協議)\n * - 錯誤處理與快取錯誤結果\n */\n\nimport { PackageNotFoundError, VersionNotFoundError, Options } from 'package-json';\nimport Bluebird from 'bluebird';\nimport { getCache } from './cacheAgent';\nimport { _createCacheKey } from './createCacheKey';\nimport { _queryVersion } from './core';\nimport { queryVersionCacheRaw } from './queryVersionCacheRaw';\nimport { IOptionsQueryVersion } from './types';\nimport { handleAmpersandAndSpaces } from '@lazy-node/semver-ampersand/lib/handleAmpersandAndSpaces';\nimport { reAmpersandAndSpaces } from '@lazy-node/semver-ampersand/lib/const';\n\n/**\n * Query package version with LRU cache.\n * 使用 LRU 快取查詢套件版本。\n *\n * @param name - Package name / 套件名稱\n * @param targetVersion - Target version or range (default: 'latest') / 目標版本或範圍\n * @param options - Query options / 查詢選項\n * @returns Promise resolving to version string / 回傳版本字串的 Promise\n *\n * @example\n * ```ts\n * const version = await queryVersionWithCache('lodash');\n * // => '4.17.21'\n *\n * const version = await queryVersionWithCache('typescript', '^4.0.0');\n * // => '4.9.5'\n * ```\n */\nexport function queryVersionWithCache(name: string, targetVersion: string = 'latest', options?: IOptionsQueryVersion<Options>): Bluebird<string>\n{\n\treturn Bluebird.resolve(queryVersionCacheRaw(name, targetVersion, options))\n\t\t.then(data =>\n\t\t{\n\t\t\t/**\n\t\t\t * 快取存有先前的失敗紀錄時直接重拋:\n\t\t\t * 同一組 name/version 短時間內重試通常仍會失敗,\n\t\t\t * 再打一次 registry 只是白白拖慢流程。\n\t\t\t *\n\t\t\t * A cached failure is rethrown immediately: retrying the same name/version\n\t\t\t * right away would almost certainly fail again, so another registry call\n\t\t\t * would only slow things down.\n\t\t\t */\n\t\t\tif (data?.error)\n\t\t\t{\n\t\t\t\treturn Promise.reject(data.error)\n\t\t\t}\n\t\t\t/**\n\t\t\t * 快取命中成功結果時直接回傳,略過網路請求。\n\t\t\t *\n\t\t\t * A cached success is returned as-is, skipping the network request.\n\t\t\t */\n\t\t\telse if (data?.result)\n\t\t\t{\n\t\t\t\treturn data.result\n\t\t\t}\n\n\t\t\t/**\n\t\t\t * 未命中(或快取列只有 version 欄位)時才真的發起查詢。\n\t\t\t *\n\t\t\t * Only a real query happens on a miss (or when the entry only carries `version`).\n\t\t\t */\n\t\t\treturn queryVersion(name, data?.version ?? targetVersion, true,options)\n\t\t\t\t.catch(e => {\n\t\t\t\t\t/**\n\t\t\t\t\t * 查詢失敗時的後備 (Fallback):若快取中已有成功結果則改採快取值,\n\t\t\t\t\t * 只有完全沒有可用結果時才把錯誤拋回給呼叫端。\n\t\t\t\t\t *\n\t\t\t\t\t * Fallback on failure: prefer an already-cached success when one exists,\n\t\t\t\t\t * and only rethrow to the caller when no usable result is available.\n\t\t\t\t\t */\n\t\t\t\t\tif (data?.result)\n\t\t\t\t\t{\n\t\t\t\t\t\treturn data.result\n\t\t\t\t\t}\n\n\t\t\t\t\treturn Promise.reject(e)\n\t\t\t\t})\n\t\t})\n}\n\n/**\n * 查詢版本的核心流程:registry 查詢 → 失敗時正規化版本重試 → 結果回寫快取。\n *\n * Core query flow: registry lookup → normalise the version and retry on failure →\n * write the outcome back to the cache.\n *\n * @param name 套件名稱 / Package name\n * @param targetVersion 目標版本或範圍,預設 latest / Target version or range, defaults to latest\n * @param save 是否將結果寫回快取;正規化後的遞迴重試傳 false / Whether to write the outcome back to the cache; pass false for the normalised retry\n * @param options 查詢與快取選項 / Query and cache options\n * @returns 解析出的版本字串 / The resolved version string\n */\nexport function queryVersion(name: string, targetVersion: string = 'latest', save: boolean = true, options?: IOptionsQueryVersion<Options>): Bluebird<string>\n{\n\t/**\n\t * ??= 補齊預設版本;快取鍵以補齊後的版本建立,\n\t * 讓「省略 targetVersion」與「顯式傳入 'latest'」共用同一筆快取。\n\t *\n\t * ??= fills in the default; the cache key is built from the normalised version so\n\t * \"omit targetVersion\" and an explicit 'latest' share the same cache entry.\n\t */\n\tlet version = targetVersion ??= 'latest';\n\tlet key = _createCacheKey(name, targetVersion);\n\n\treturn _queryVersion(name, {\n\t\tversion,\n\t})\n\t\t.then((result) =>\n\t\t{\n\t\t\treturn result.version\n\t\t})\n\t\t.catch(VersionNotFoundError, async (e) =>\n\t\t{\n\t\t\t/**\n\t\t\t * bool 表示「版本是否已被正規化」;\n\t\t\t * 只有真的改寫過才值得用新版本重試一次。\n\t\t\t *\n\t\t\t * `bool` tracks whether the version was actually normalised;\n\t\t\t * only a rewritten version is worth one retry.\n\t\t\t */\n\t\t\tlet bool = true;\n\n\t\t\t/**\n\t\t\t * npm: 別名協定 (Alias Protocol) 的字串 registry 無法直接解析,\n\t\t\t * 剝掉前綴後以剩餘規格重試(例如 `npm:foo@1.0.0` → `foo@1.0.0`)。\n\t\t\t *\n\t\t\t * The npm: alias protocol is not parseable by the registry as-is,\n\t\t\t * so the prefix is stripped and the remainder retried.\n\t\t\t */\n\t\t\tif (version.startsWith('npm:'))\n\t\t\t{\n\t\t\t\tversion = version.replace(/^npm:/, '')\n\n\t\t\t\tbool = false\n\t\t\t}\n\n\t\t\t/**\n\t\t\t * 版本範圍中的 `&` 與空白(常見於套件管理器產生的範圍)需先正規化,\n\t\t\t * 否則 registry 端的 semver 解析會失敗。\n\t\t\t *\n\t\t\t * `&` and whitespace inside a range (common in package-manager output)\n\t\t\t * must be normalised first, otherwise semver parsing fails upstream.\n\t\t\t */\n\t\t\tif (reAmpersandAndSpaces.test(version))\n\t\t\t{\n\t\t\t\tversion = handleAmpersandAndSpaces(version)\n\n\t\t\t\tbool = false\n\t\t\t}\n\n\t\t\t/**\n\t\t\t * 兩種正規化都沒套用時,重試只會得到相同的錯誤;\n\t\t\t * 直接重拋原錯誤,避免以相同輸入無限遞迴。\n\t\t\t *\n\t\t\t * When neither normalisation applied, a retry would hit the same error;\n\t\t\t * rethrow immediately to avoid infinite recursion on identical input.\n\t\t\t */\n\t\t\tif (bool)\n\t\t\t{\n\t\t\t\treturn Promise.reject(e)\n\t\t\t}\n\n\t\t\t/**\n\t\t\t * 以正規化後的版本重試;save=false 是為了避免遞迴呼叫重複寫入快取,\n\t\t\t * 外層的 tap / tapCatch 仍會以原始 key 記錄最終結果。\n\t\t\t *\n\t\t\t * Retry with the normalised version; save=false prevents the recursive call\n\t\t\t * from double-writing the cache — the outer tap / tapCatch still records\n\t\t\t * the final outcome under the original key.\n\t\t\t */\n\t\t\treturn queryVersion(name, version, false,options)\n\t\t})\n\t\t.tapCatch(VersionNotFoundError, PackageNotFoundError, (error) =>\n\t\t{\n\t\t\t/**\n\t\t\t * 負面快取 (Negative Cache):把「版本/套件不存在」也記下來,\n\t\t\t * 避免每次呼叫都重複打 registry 查詢一個確定失敗的目標。\n\t\t\t *\n\t\t\t * Negative cache: remember \"version/package not found\" so repeated calls\n\t\t\t * do not re-query a target that is known to fail.\n\t\t\t */\n\t\t\tsave && getCache(options).set(key, {\n\t\t\t\tkey,\n\t\t\t\tname,\n\t\t\t\tversion,\n\t\t\t\terror,\n\t\t\t});\n\t\t})\n\t\t.tap(result =>\n\t\t{\n\t\t\t/**\n\t\t\t * 成功結果寫回快取,供後續查詢直接命中。\n\t\t\t *\n\t\t\t * Write the successful result back so later lookups hit the cache.\n\t\t\t */\n\t\t\tsave && getCache(options).set(key, {\n\t\t\t\tkey,\n\t\t\t\tname,\n\t\t\t\tversion,\n\t\t\t\tresult,\n\t\t\t});\n\t\t})\n\t\t;\n}\n\nexport default queryVersionWithCache\n"]}
@@ -1,13 +1,48 @@
1
1
  import { IResult } from '@yarn-tool/npm-package-arg-util';
2
2
  import { IOptionsQueryVersion } from './types';
3
3
  import { Options } from 'package-json';
4
+ /**
5
+ * 把 npm 套件參數字串(如 `lodash@^4.0.0`)解析成名稱與版本兩段,
6
+ * 對應 npm/yarn 指令列慣用的 `<pkg>[@<version>]` 語法,
7
+ * 讓呼叫端不必自己切字串(版本範圍內可能含 @,手動分割會切錯)。
8
+ *
9
+ * Parses an npm package argument string such as `lodash@^4.0.0` into name + version,
10
+ * matching the `<pkg>[@<version>]` CLI convention. Hand-splitting is avoided because
11
+ * a version range itself may contain `@` (e.g. `@scope/pkg@^1.0.0`).
12
+ *
13
+ * @param input npm 套件參數字串 / npm package argument string
14
+ * @returns 名稱與版本物件 / An object holding name and version
15
+ */
4
16
  export declare function parseVersionByNpmPackageArg(input: string): {
5
17
  name: string;
6
18
  version: string;
7
19
  };
20
+ /**
21
+ * 從 npa 解析結果取出本次查詢真正需要的欄位,
22
+ * 拆成 core 版是為了隔離 npa 的回傳型別,避免其內部型別變動影響對外 API。
23
+ *
24
+ * Extracts only the fields this package needs from an npa result.
25
+ * The core split isolates npa's return type so its internal type changes
26
+ * do not leak into this package's public API.
27
+ *
28
+ * @param result npa 的解析結果 / An npa parse result
29
+ * @returns 名稱與版本物件 / An object holding name and version
30
+ */
8
31
  export declare function _parseVersionByNpmPackageArgCore(result: IResult): {
9
32
  name: string;
10
33
  version: string;
11
34
  };
35
+ /**
36
+ * 以 npm 套件參數語法查詢版本(含快取),
37
+ * 等同於先 parse 再呼叫 queryVersionWithCache,方便直接吃 CLI 風格輸入。
38
+ *
39
+ * Queries a version with cache support using npm package argument syntax;
40
+ * equivalent to parsing first and then calling queryVersionWithCache,
41
+ * which lets callers pass CLI-style input directly.
42
+ *
43
+ * @param input npm 套件參數字串,如 `lodash@^4.0.0` / npm package argument, e.g. `lodash@^4.0.0`
44
+ * @param options 查詢與快取選項 / Query and cache options
45
+ * @returns 解析出的版本字串 / The resolved version string
46
+ */
12
47
  export declare function queryVersionByNpmPackageArgWithCache(input: string, options?: IOptionsQueryVersion<Options>): import("bluebird")<string>;
13
48
  export default queryVersionByNpmPackageArgWithCache;
@@ -5,9 +5,32 @@ exports._parseVersionByNpmPackageArgCore = _parseVersionByNpmPackageArgCore;
5
5
  exports.queryVersionByNpmPackageArgWithCache = queryVersionByNpmPackageArgWithCache;
6
6
  const npm_package_arg_util_1 = require("@yarn-tool/npm-package-arg-util");
7
7
  const queryVersion_1 = require("./queryVersion");
8
+ /**
9
+ * 把 npm 套件參數字串(如 `lodash@^4.0.0`)解析成名稱與版本兩段,
10
+ * 對應 npm/yarn 指令列慣用的 `<pkg>[@<version>]` 語法,
11
+ * 讓呼叫端不必自己切字串(版本範圍內可能含 @,手動分割會切錯)。
12
+ *
13
+ * Parses an npm package argument string such as `lodash@^4.0.0` into name + version,
14
+ * matching the `<pkg>[@<version>]` CLI convention. Hand-splitting is avoided because
15
+ * a version range itself may contain `@` (e.g. `@scope/pkg@^1.0.0`).
16
+ *
17
+ * @param input npm 套件參數字串 / npm package argument string
18
+ * @returns 名稱與版本物件 / An object holding name and version
19
+ */
8
20
  function parseVersionByNpmPackageArg(input) {
9
21
  return _parseVersionByNpmPackageArgCore((0, npm_package_arg_util_1.npa)(input));
10
22
  }
23
+ /**
24
+ * 從 npa 解析結果取出本次查詢真正需要的欄位,
25
+ * 拆成 core 版是為了隔離 npa 的回傳型別,避免其內部型別變動影響對外 API。
26
+ *
27
+ * Extracts only the fields this package needs from an npa result.
28
+ * The core split isolates npa's return type so its internal type changes
29
+ * do not leak into this package's public API.
30
+ *
31
+ * @param result npa 的解析結果 / An npa parse result
32
+ * @returns 名稱與版本物件 / An object holding name and version
33
+ */
11
34
  function _parseVersionByNpmPackageArgCore(result) {
12
35
  const { name, fetchSpec: version } = result;
13
36
  return {
@@ -15,6 +38,18 @@ function _parseVersionByNpmPackageArgCore(result) {
15
38
  version,
16
39
  };
17
40
  }
41
+ /**
42
+ * 以 npm 套件參數語法查詢版本(含快取),
43
+ * 等同於先 parse 再呼叫 queryVersionWithCache,方便直接吃 CLI 風格輸入。
44
+ *
45
+ * Queries a version with cache support using npm package argument syntax;
46
+ * equivalent to parsing first and then calling queryVersionWithCache,
47
+ * which lets callers pass CLI-style input directly.
48
+ *
49
+ * @param input npm 套件參數字串,如 `lodash@^4.0.0` / npm package argument, e.g. `lodash@^4.0.0`
50
+ * @param options 查詢與快取選項 / Query and cache options
51
+ * @returns 解析出的版本字串 / The resolved version string
52
+ */
18
53
  function queryVersionByNpmPackageArgWithCache(input, options) {
19
54
  const { name, version } = parseVersionByNpmPackageArg(input);
20
55
  return (0, queryVersion_1.queryVersionWithCache)(name, version, options);
@@ -1 +1 @@
1
- {"version":3,"file":"queryVersionByNpmPackageArg.js","sourceRoot":"","sources":["queryVersionByNpmPackageArg.ts"],"names":[],"mappings":";;AAKA,kEAGC;AAED,4EAQC;AAED,oFAKC;AAzBD,0EAA+D;AAC/D,iDAAuD;AAIvD,SAAgB,2BAA2B,CAAC,KAAa;IAExD,OAAO,gCAAgC,CAAC,IAAA,0BAAG,EAAC,KAAK,CAAC,CAAC,CAAA;AACpD,CAAC;AAED,SAAgB,gCAAgC,CAAC,MAAe;IAE/D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE5C,OAAO;QACN,IAAI;QACJ,OAAO;KACP,CAAA;AACF,CAAC;AAED,SAAgB,oCAAoC,CAAC,KAAa,EAAE,OAAuC;IAE1G,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAE7D,OAAO,IAAA,oCAAqB,EAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AACrD,CAAC;AAED,kBAAe,oCAAoC,CAAA","sourcesContent":["import { npa, IResult } from '@yarn-tool/npm-package-arg-util';\nimport { queryVersionWithCache } from './queryVersion';\nimport { IOptionsQueryVersion } from './types';\nimport { Options } from 'package-json';\n\nexport function parseVersionByNpmPackageArg(input: string)\n{\n\treturn _parseVersionByNpmPackageArgCore(npa(input))\n}\n\nexport function _parseVersionByNpmPackageArgCore(result: IResult)\n{\n\tconst { name, fetchSpec: version } = result;\n\n\treturn {\n\t\tname,\n\t\tversion,\n\t}\n}\n\nexport function queryVersionByNpmPackageArgWithCache(input: string, options?: IOptionsQueryVersion<Options>)\n{\n\tconst { name, version } = parseVersionByNpmPackageArg(input);\n\n\treturn queryVersionWithCache(name, version, options)\n}\n\nexport default queryVersionByNpmPackageArgWithCache\n"]}
1
+ {"version":3,"file":"queryVersionByNpmPackageArg.js","sourceRoot":"","sources":["queryVersionByNpmPackageArg.ts"],"names":[],"mappings":";;AAiBA,kEAGC;AAaD,4EAQC;AAcD,oFAKC;AA5DD,0EAA+D;AAC/D,iDAAuD;AAIvD;;;;;;;;;;;GAWG;AACH,SAAgB,2BAA2B,CAAC,KAAa;IAExD,OAAO,gCAAgC,CAAC,IAAA,0BAAG,EAAC,KAAK,CAAC,CAAC,CAAA;AACpD,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,gCAAgC,CAAC,MAAe;IAE/D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE5C,OAAO;QACN,IAAI;QACJ,OAAO;KACP,CAAA;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,oCAAoC,CAAC,KAAa,EAAE,OAAuC;IAE1G,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IAE7D,OAAO,IAAA,oCAAqB,EAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AACrD,CAAC;AAED,kBAAe,oCAAoC,CAAA","sourcesContent":["import { npa, IResult } from '@yarn-tool/npm-package-arg-util';\nimport { queryVersionWithCache } from './queryVersion';\nimport { IOptionsQueryVersion } from './types';\nimport { Options } from 'package-json';\n\n/**\n * 把 npm 套件參數字串(如 `lodash@^4.0.0`)解析成名稱與版本兩段,\n * 對應 npm/yarn 指令列慣用的 `<pkg>[@<version>]` 語法,\n * 讓呼叫端不必自己切字串(版本範圍內可能含 @,手動分割會切錯)。\n *\n * Parses an npm package argument string such as `lodash@^4.0.0` into name + version,\n * matching the `<pkg>[@<version>]` CLI convention. Hand-splitting is avoided because\n * a version range itself may contain `@` (e.g. `@scope/pkg@^1.0.0`).\n *\n * @param input npm 套件參數字串 / npm package argument string\n * @returns 名稱與版本物件 / An object holding name and version\n */\nexport function parseVersionByNpmPackageArg(input: string)\n{\n\treturn _parseVersionByNpmPackageArgCore(npa(input))\n}\n\n/**\n * 從 npa 解析結果取出本次查詢真正需要的欄位,\n * 拆成 core 版是為了隔離 npa 的回傳型別,避免其內部型別變動影響對外 API。\n *\n * Extracts only the fields this package needs from an npa result.\n * The core split isolates npa's return type so its internal type changes\n * do not leak into this package's public API.\n *\n * @param result npa 的解析結果 / An npa parse result\n * @returns 名稱與版本物件 / An object holding name and version\n */\nexport function _parseVersionByNpmPackageArgCore(result: IResult)\n{\n\tconst { name, fetchSpec: version } = result;\n\n\treturn {\n\t\tname,\n\t\tversion,\n\t}\n}\n\n/**\n * 以 npm 套件參數語法查詢版本(含快取),\n * 等同於先 parse 再呼叫 queryVersionWithCache,方便直接吃 CLI 風格輸入。\n *\n * Queries a version with cache support using npm package argument syntax;\n * equivalent to parsing first and then calling queryVersionWithCache,\n * which lets callers pass CLI-style input directly.\n *\n * @param input npm 套件參數字串,如 `lodash@^4.0.0` / npm package argument, e.g. `lodash@^4.0.0`\n * @param options 查詢與快取選項 / Query and cache options\n * @returns 解析出的版本字串 / The resolved version string\n */\nexport function queryVersionByNpmPackageArgWithCache(input: string, options?: IOptionsQueryVersion<Options>)\n{\n\tconst { name, version } = parseVersionByNpmPackageArg(input);\n\n\treturn queryVersionWithCache(name, version, options)\n}\n\nexport default queryVersionByNpmPackageArgWithCache\n"]}
@@ -1,3 +1,16 @@
1
1
  import { IOptionsQueryVersion } from './types';
2
2
  import { Options } from 'package-json';
3
+ /**
4
+ * 只讀快取查詢:命中時回傳快取內容,未命中回傳 undefined,
5
+ * 完全不觸碰 npm registry,讓呼叫端得以在真正發起網路請求前先判斷快取狀態。
6
+ *
7
+ * Read-only cache lookup: returns the cached entry when present and undefined otherwise,
8
+ * never touching the npm registry, so callers can inspect the cache state
9
+ * before deciding whether a real network request is needed.
10
+ *
11
+ * @param name 套件名稱 / Package name
12
+ * @param targetVersion 目標版本或範圍,預設 latest / Target version or range, defaults to latest
13
+ * @param options 查詢與快取選項 / Query and cache options
14
+ * @returns 快取中的查詢結果,未命中為 undefined / Cached result, or undefined on a miss
15
+ */
3
16
  export declare function queryVersionCacheRaw(name: string, targetVersion: string, options: IOptionsQueryVersion<Options>): import("./types").ICachedVersionResult;
@@ -3,6 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.queryVersionCacheRaw = queryVersionCacheRaw;
4
4
  const createCacheKey_1 = require("./createCacheKey");
5
5
  const cacheAgent_1 = require("./cacheAgent");
6
+ /**
7
+ * 只讀快取查詢:命中時回傳快取內容,未命中回傳 undefined,
8
+ * 完全不觸碰 npm registry,讓呼叫端得以在真正發起網路請求前先判斷快取狀態。
9
+ *
10
+ * Read-only cache lookup: returns the cached entry when present and undefined otherwise,
11
+ * never touching the npm registry, so callers can inspect the cache state
12
+ * before deciding whether a real network request is needed.
13
+ *
14
+ * @param name 套件名稱 / Package name
15
+ * @param targetVersion 目標版本或範圍,預設 latest / Target version or range, defaults to latest
16
+ * @param options 查詢與快取選項 / Query and cache options
17
+ * @returns 快取中的查詢結果,未命中為 undefined / Cached result, or undefined on a miss
18
+ */
6
19
  function queryVersionCacheRaw(name, targetVersion = 'latest', options) {
7
20
  let key = (0, createCacheKey_1._createCacheKey)(name, targetVersion);
8
21
  return (0, cacheAgent_1.getCache)(options).get(key);
@@ -1 +1 @@
1
- {"version":3,"file":"queryVersionCacheRaw.js","sourceRoot":"","sources":["queryVersionCacheRaw.ts"],"names":[],"mappings":";;AAKA,oDAIC;AATD,qDAAmD;AACnD,6CAAwC;AAIxC,SAAgB,oBAAoB,CAAC,IAAY,EAAE,gBAAwB,QAAQ,EAAE,OAAsC;IAE1H,IAAI,GAAG,GAAG,IAAA,gCAAe,EAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAC/C,OAAO,IAAA,qBAAQ,EAAC,OAAO,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC","sourcesContent":["import { _createCacheKey } from './createCacheKey';\nimport { getCache } from './cacheAgent';\nimport { IOptionsQueryVersion } from './types';\nimport { Options } from 'package-json';\n\nexport function queryVersionCacheRaw(name: string, targetVersion: string = 'latest', options: IOptionsQueryVersion<Options>)\n{\n\tlet key = _createCacheKey(name, targetVersion);\n\treturn getCache(options).get(key);\n}\n"]}
1
+ {"version":3,"file":"queryVersionCacheRaw.js","sourceRoot":"","sources":["queryVersionCacheRaw.ts"],"names":[],"mappings":";;AAkBA,oDAIC;AAtBD,qDAAmD;AACnD,6CAAwC;AAIxC;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,IAAY,EAAE,gBAAwB,QAAQ,EAAE,OAAsC;IAE1H,IAAI,GAAG,GAAG,IAAA,gCAAe,EAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IAC/C,OAAO,IAAA,qBAAQ,EAAC,OAAO,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC","sourcesContent":["import { _createCacheKey } from './createCacheKey';\nimport { getCache } from './cacheAgent';\nimport { IOptionsQueryVersion } from './types';\nimport { Options } from 'package-json';\n\n/**\n * 只讀快取查詢:命中時回傳快取內容,未命中回傳 undefined,\n * 完全不觸碰 npm registry,讓呼叫端得以在真正發起網路請求前先判斷快取狀態。\n *\n * Read-only cache lookup: returns the cached entry when present and undefined otherwise,\n * never touching the npm registry, so callers can inspect the cache state\n * before deciding whether a real network request is needed.\n *\n * @param name 套件名稱 / Package name\n * @param targetVersion 目標版本或範圍,預設 latest / Target version or range, defaults to latest\n * @param options 查詢與快取選項 / Query and cache options\n * @returns 快取中的查詢結果,未命中為 undefined / Cached result, or undefined on a miss\n */\nexport function queryVersionCacheRaw(name: string, targetVersion: string = 'latest', options: IOptionsQueryVersion<Options>)\n{\n\tlet key = _createCacheKey(name, targetVersion);\n\treturn getCache(options).get(key);\n}\n"]}
package/lib/types.d.ts CHANGED
@@ -14,15 +14,39 @@ import Cache, { IOptionsLRUCacheFS } from 'lru-cache-fs2';
14
14
  * 快取版本查詢結果的核心結構。
15
15
  */
16
16
  export interface ICachedVersionResultCore {
17
+ /** 快取鍵,格式為 `name@version` / Cache key in `name@version` form */
17
18
  key: string;
19
+ /** 套件名稱 / Package name */
18
20
  name: string;
21
+ /** 被查詢的版本或範圍 / The queried version or range */
19
22
  version: string;
23
+ /** 查詢成功時的解析結果 / Resolved version when the query succeeded */
20
24
  result?: string;
25
+ /** 查詢失敗時的錯誤物件 / Error captured when the query failed */
21
26
  error?: VersionNotFoundError | PackageNotFoundError;
22
27
  }
28
+ /**
29
+ * 快取結果至少要有 result 或 error 其中之一,
30
+ * 以型別逼出「既沒成功也沒失敗」這種無法解釋的快取列。
31
+ *
32
+ * A cached entry must carry either result or error, so the type system rules out
33
+ * entries that are neither a success nor a failure (which would be uninterpretable).
34
+ */
23
35
  export type ICachedVersionResult = ITSRequireAtLeastOne<ICachedVersionResultCore, 'result' | 'error'>;
36
+ /**
37
+ * 查詢選項:交叉 package-json 的選項(registry 相關設定可直接透傳)
38
+ * 與本套件自己的快取 / 錯誤處理欄位。
39
+ *
40
+ * Query options: an intersection of package-json's options (registry settings pass
41
+ * straight through) with this package's own cache and error-handling fields.
42
+ *
43
+ * @template T 底層 package-json 的選項型別 / Underlying package-json options type
44
+ */
24
45
  export type IOptionsQueryVersion<T extends Options | AbbreviatedMetadata> = T & {
46
+ /** 失敗時回傳 undefined 而非丟出例外 / Return undefined instead of throwing on failure */
25
47
  notThrowError?: boolean;
48
+ /** 自訂快取實例,優先於內建單例 / Custom cache instance, takes precedence over the built-in singleton */
26
49
  cacheAgent?: Cache<string, ICachedVersionResult>;
50
+ /** 建立內建快取時使用的 LRU 設定 / LRU settings used when building the built-in cache */
27
51
  cacheAgentOptions?: IOptionsLRUCacheFS<string, ICachedVersionResult>;
28
52
  };
package/lib/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG","sourcesContent":["/**\n * Type definitions for @yarn-tool/pkg-version-query.\n * @yarn-tool/pkg-version-query 的類型定義。\n *\n * @packageDocumentation\n *\n * 包含版本查詢結果、快取選項等相關類型定義。\n */\n\nimport { VersionNotFoundError, PackageNotFoundError, Options, AbbreviatedMetadata } from 'package-json';\nimport { ITSRequireAtLeastOne } from 'ts-type/lib/type/record';\nimport Cache, { IOptionsLRUCacheFS } from 'lru-cache-fs2';\n\n/**\n * Core structure for cached version query result.\n * 快取版本查詢結果的核心結構。\n */\nexport interface ICachedVersionResultCore\n{\n\tkey: string,\n\tname: string;\n\tversion: string;\n\tresult?: string;\n\terror?: VersionNotFoundError | PackageNotFoundError;\n}\n\nexport type ICachedVersionResult = ITSRequireAtLeastOne<ICachedVersionResultCore, 'result' | 'error'>\n\nexport type IOptionsQueryVersion<T extends Options | AbbreviatedMetadata> = T & {\n\n\tnotThrowError?: boolean,\n\n\tcacheAgent?: Cache<string, ICachedVersionResult>;\n\tcacheAgentOptions?: IOptionsLRUCacheFS<string, ICachedVersionResult>;\n\n}\n"]}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG","sourcesContent":["/**\n * Type definitions for @yarn-tool/pkg-version-query.\n * @yarn-tool/pkg-version-query 的類型定義。\n *\n * @packageDocumentation\n *\n * 包含版本查詢結果、快取選項等相關類型定義。\n */\n\nimport { VersionNotFoundError, PackageNotFoundError, Options, AbbreviatedMetadata } from 'package-json';\nimport { ITSRequireAtLeastOne } from 'ts-type/lib/type/record';\nimport Cache, { IOptionsLRUCacheFS } from 'lru-cache-fs2';\n\n/**\n * Core structure for cached version query result.\n * 快取版本查詢結果的核心結構。\n */\nexport interface ICachedVersionResultCore\n{\n\t/** 快取鍵,格式為 `name@version` / Cache key in `name@version` form */\n\tkey: string,\n\t/** 套件名稱 / Package name */\n\tname: string;\n\t/** 被查詢的版本或範圍 / The queried version or range */\n\tversion: string;\n\t/** 查詢成功時的解析結果 / Resolved version when the query succeeded */\n\tresult?: string;\n\t/** 查詢失敗時的錯誤物件 / Error captured when the query failed */\n\terror?: VersionNotFoundError | PackageNotFoundError;\n}\n\n/**\n * 快取結果至少要有 result 或 error 其中之一,\n * 以型別逼出「既沒成功也沒失敗」這種無法解釋的快取列。\n *\n * A cached entry must carry either result or error, so the type system rules out\n * entries that are neither a success nor a failure (which would be uninterpretable).\n */\nexport type ICachedVersionResult = ITSRequireAtLeastOne<ICachedVersionResultCore, 'result' | 'error'>\n\n/**\n * 查詢選項:交叉 package-json 的選項(registry 相關設定可直接透傳)\n * 與本套件自己的快取 / 錯誤處理欄位。\n *\n * Query options: an intersection of package-json's options (registry settings pass\n * straight through) with this package's own cache and error-handling fields.\n *\n * @template T 底層 package-json 的選項型別 / Underlying package-json options type\n */\nexport type IOptionsQueryVersion<T extends Options | AbbreviatedMetadata> = T & {\n\n\t/** 失敗時回傳 undefined 而非丟出例外 / Return undefined instead of throwing on failure */\n\tnotThrowError?: boolean,\n\n\t/** 自訂快取實例,優先於內建單例 / Custom cache instance, takes precedence over the built-in singleton */\n\tcacheAgent?: Cache<string, ICachedVersionResult>;\n\t/** 建立內建快取時使用的 LRU 設定 / LRU settings used when building the built-in cache */\n\tcacheAgentOptions?: IOptionsLRUCacheFS<string, ICachedVersionResult>;\n\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yarn-tool/pkg-version-query",
3
- "version": "3.0.9",
3
+ "version": "3.0.11",
4
4
  "description": "Query package versions from npm registry with LRU cache support. Supports version ranges, npm: protocol, and semver syntax handling. 從 npm registry 查詢套件版本,支援 LRU 快取、版本範圍語法與 npm: 協議處理。",
5
5
  "keywords": [
6
6
  "npm",
@@ -33,35 +33,37 @@
33
33
  "author": "bluelovers",
34
34
  "main": "index.js",
35
35
  "scripts": {
36
- "coverage": "yarn run test -- --coverage",
36
+ "coverage": "pnpm run test -- --coverage",
37
37
  "lint": "ynpx --quiet eslint -- **/*.ts",
38
- "test": "jest",
38
+ "test": "node --run test:node",
39
39
  "test:jest": "ynpx --quiet jest -- --coverage",
40
- "test:jest:coverage": "yarn run test:jest -- --coverage",
41
- "test:jest:snapshot": "yarn run test:jest -- -u",
40
+ "test:jest:coverage": "pnpm run test:jest -- --coverage",
41
+ "test:jest:snapshot": "pnpm run test:jest -- -u",
42
42
  "test:mocha": "ynpx --quiet -p ts-node -p mocha mocha -- --require ts-node/register \"!(node_modules)/**/*.{test,spec}.{ts,tsx}\"",
43
- "test:snapshot": "yarn run test -- -u",
43
+ "test:node": "tsx --test --test-update-snapshots **/*.node-spec.ts **/*.node-test.ts **/*.spec.ts **/*.test.ts",
44
+ "test:snapshot": "pnpm run test -u",
45
+ "test:tsc": "tsc --noEmit & echo typescript check done",
44
46
  "test:tsd": "ynpx tsd",
45
- "preversion": "yarn run test",
47
+ "preversion": "pnpm run test",
46
48
  "prepublishOnly": "echo prepublishOnly",
47
49
  "prepublishOnly:check-bin": "ynpx --quiet @yarn-tool/check-pkg-bin",
48
- "prepublishOnly:update": "yarn run ncu && yarn run sort-package-json",
50
+ "prepublishOnly:update": "pnpm run ncu && pnpm run sort-package-json",
49
51
  "ncu": "yarn-tool ncu -u",
50
52
  "sort-package-json": "yarn-tool sort",
51
53
  "tsc:showConfig": "ynpx get-current-tsconfig -p"
52
54
  },
53
55
  "dependencies": {
54
- "@lazy-node/semver-ampersand": "^3.0.10",
55
- "@yarn-tool/npm-package-arg-util": "^2.0.7",
56
- "cache-path": "^4.0.11",
56
+ "@lazy-node/semver-ampersand": "^3.0.12",
57
+ "@yarn-tool/npm-package-arg-util": "^2.0.9",
58
+ "cache-path": "^4.0.13",
57
59
  "lru-cache-fs2": "^2.0.8",
58
60
  "package-json": "<7 >=6.5",
59
- "semver": "^7.7.4",
60
- "ts-type": "^3.0.13",
61
+ "semver": "^7.8.5",
62
+ "ts-type": "^3.0.18",
61
63
  "tslib": ">=2.8.1"
62
64
  },
63
65
  "publishConfig": {
64
66
  "access": "public"
65
67
  },
66
- "gitHead": "8c939a673ef0f088d4a3aa8a240ed6c28d390f98"
68
+ "gitHead": "471c63ee11851f0ac3487f23d1c472936f99b460"
67
69
  }