@yarn-tool/npa-to-deps-query 3.0.10 → 3.0.12
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 +43 -0
- package/README.md +87 -41
- package/index.d.ts +74 -0
- package/index.js +107 -0
- package/index.js.map +1 -1
- package/package.json +15 -8
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,49 @@
|
|
|
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.12](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/npa-to-deps-query@3.0.11...@yarn-tool/npa-to-deps-query@3.0.12) (2026-10-12)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### 🔖 Miscellaneous
|
|
11
|
+
|
|
12
|
+
* . ([2ce14fc](https://github.com/bluelovers/ws-yarn-workspaces/commit/2ce14fcf8272584c51c4ba43b87a488f105c2f63))
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
## [3.0.11](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/npa-to-deps-query@3.0.10...@yarn-tool/npa-to-deps-query@3.0.11) (2026-10-12)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
### 📚 Documentation
|
|
21
|
+
|
|
22
|
+
* add jsdoc ([9cb9b13](https://github.com/bluelovers/ws-yarn-workspaces/commit/9cb9b13eda8c357221ad1b754458aa9916eada22))
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
### 🚨 Tests
|
|
26
|
+
|
|
27
|
+
* **snap:** update snapshots ([c9945a5](https://github.com/bluelovers/ws-yarn-workspaces/commit/c9945a5b9cd723d38ded2a69b83e2e83ecc3b524))
|
|
28
|
+
* **test:** 將測試框架從 jest 遷移至 node:test ([3af9774](https://github.com/bluelovers/ws-yarn-workspaces/commit/3af9774964abc48083ec60b2021c1cec08874803))
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### 🛠 Build System
|
|
32
|
+
|
|
33
|
+
* update build ([3186340](https://github.com/bluelovers/ws-yarn-workspaces/commit/3186340758172427cb1e9b8955f6fd677abac625))
|
|
34
|
+
* **deps:** 更新測試腳本與依賴以支援 node:test ([f9c71c7](https://github.com/bluelovers/ws-yarn-workspaces/commit/f9c71c795c792c5c7ed9d613ce7e9c3c726c39d5))
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
### ♻️ Chores
|
|
38
|
+
|
|
39
|
+
* **deps:** 更新各套件依賴版本 ([569f075](https://github.com/bluelovers/ws-yarn-workspaces/commit/569f0756189cdadf69955d8e388ac0a6a8988056))
|
|
40
|
+
* **workspace:** 更新測試指令路徑與新增工作區搜尋選項 ([a80039d](https://github.com/bluelovers/ws-yarn-workspaces/commit/a80039dd8c691e047466966ffc8f8a4e2e31c03f))
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
### 🔖 Miscellaneous
|
|
44
|
+
|
|
45
|
+
* . ([e5788f8](https://github.com/bluelovers/ws-yarn-workspaces/commit/e5788f84551b870490a96d0a5d67d8d542481373))
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
|
|
6
49
|
## [3.0.10](https://github.com/bluelovers/ws-yarn-workspaces/compare/@yarn-tool/npa-to-deps-query@3.0.9...@yarn-tool/npa-to-deps-query@3.0.10) (2026-09-06)
|
|
7
50
|
|
|
8
51
|
|
package/README.md
CHANGED
|
@@ -1,8 +1,17 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @yarn-tool/npa-to-deps-query
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Resolve npm-package-arg (npa) specs to concrete versions by querying the npm registry.
|
|
4
|
+
透過查詢 npm registry (Registry),將 npm-package-arg (npa) 規格解析為具體版本。
|
|
4
5
|
|
|
5
|
-
##
|
|
6
|
+
## Features / 功能特點
|
|
7
|
+
|
|
8
|
+
- 將 `name@range` 規格 (Spec) 解析為具體版本值 (Concrete Version Value),例如 `jest@^12` → `^12.1.1`
|
|
9
|
+
- 僅在結果標記為需要查詢 (fetchQuery) 時才向 registry 發送請求,其餘情況直接回傳原始範圍 (Range)
|
|
10
|
+
- 透過 `queryVersionWithCache` 使用版本查詢快取 (Cache),避免重複請求 registry
|
|
11
|
+
- 支援自訂查詢選項 (queryOptions),沿用 `package-json` 的 `Options` 設定
|
|
12
|
+
- 以 Bluebird Promise 回傳,可直接串接非同步流程 / Returns a Bluebird promise for async chaining
|
|
13
|
+
|
|
14
|
+
## Installation / 安裝
|
|
6
15
|
|
|
7
16
|
```bash
|
|
8
17
|
yarn add @yarn-tool/npa-to-deps-query
|
|
@@ -10,51 +19,88 @@ yarn-tool add @yarn-tool/npa-to-deps-query
|
|
|
10
19
|
yt add @yarn-tool/npa-to-deps-query
|
|
11
20
|
```
|
|
12
21
|
|
|
22
|
+
## Usage / 使用方式
|
|
23
|
+
|
|
13
24
|
```typescript
|
|
25
|
+
import queryDepsValueByNpa, { queryDepsValueByNpaResult } from '@yarn-tool/npa-to-deps-query';
|
|
26
|
+
|
|
27
|
+
// 一步完成解析與版本查詢 / Parse and query the version in one step
|
|
14
28
|
queryDepsValueByNpa('jest@12')
|
|
15
|
-
.tap(console.dir)
|
|
29
|
+
.tap(console.dir);
|
|
30
|
+
// => { name: 'jest', value: '12.1.1', ..., result: ... }
|
|
16
31
|
```
|
|
17
32
|
|
|
18
|
-
|
|
19
|
-
exports[`jest@<=12 1`] = `
|
|
20
|
-
Object {
|
|
21
|
-
"name": "jest",
|
|
22
|
-
"value": "<=12",
|
|
23
|
-
}
|
|
24
|
-
`;
|
|
33
|
+
已有 `@yarn-tool/npa-to-deps` 的轉換結果時,可只執行版本查詢:
|
|
25
34
|
|
|
26
|
-
|
|
27
|
-
Object {
|
|
28
|
-
"name": "jest",
|
|
29
|
-
"value": "<12",
|
|
30
|
-
}
|
|
31
|
-
`;
|
|
35
|
+
When you already have a conversion result from `@yarn-tool/npa-to-deps`, run only the version query:
|
|
32
36
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
"value": ">=12",
|
|
37
|
-
}
|
|
38
|
-
`;
|
|
37
|
+
```typescript
|
|
38
|
+
import { npaToDepsValue } from '@yarn-tool/npa-to-deps';
|
|
39
|
+
import { queryDepsValueByNpaResult } from '@yarn-tool/npa-to-deps-query';
|
|
39
40
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
}
|
|
45
|
-
`;
|
|
41
|
+
const depsResult = npaToDepsValue('jest@^12');
|
|
42
|
+
const actual = await queryDepsValueByNpaResult(depsResult);
|
|
43
|
+
// => { name: 'jest', value: '^12.1.1' }
|
|
44
|
+
```
|
|
46
45
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
46
|
+
### 範例輸出 / Example Output
|
|
47
|
+
|
|
48
|
+
以下為 `queryDepsValueByNpaResult` 對不同輸入的回傳值,`*` 表示需向 registry 查詢後才取得:
|
|
49
|
+
The values returned by `queryDepsValueByNpaResult` for different inputs; `*` marks inputs that require a registry lookup:
|
|
50
|
+
|
|
51
|
+
| 輸入 Input | 回傳值 Returned `value` |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `jest@12` | `12.1.1` * |
|
|
54
|
+
| `jest@^12` | `^12.1.1` * |
|
|
55
|
+
| `jest@>12` | `>12` |
|
|
56
|
+
| `jest@<12` | `<12` |
|
|
57
|
+
| `jest@>=12` | `>=12` |
|
|
58
|
+
| `jest@<=12` | `<=12` |
|
|
59
|
+
|
|
60
|
+
## API Documentation / API 文件
|
|
53
61
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
62
|
+
### `queryDepsValueByNpa(input: string, options?: IOptions)`
|
|
63
|
+
|
|
64
|
+
解析套件規格字串,必要時向 registry 查詢版本,回傳合併後的依賴值 (Merged Dependency Value)。
|
|
65
|
+
Parses a package spec string, queries the registry when needed, and returns the merged dependency value.
|
|
66
|
+
|
|
67
|
+
**Parameters / 參數:**
|
|
68
|
+
- `input` - The package spec string, e.g. `jest@^12` / 套件規格字串,例如 `jest@^12`
|
|
69
|
+
- `options` - Parsing, conversion and query options / 解析、轉換與查詢選項
|
|
70
|
+
|
|
71
|
+
**Returns / 回傳:**
|
|
72
|
+
- Promise resolving to the `IDepsResult` fields merged with `name` and `value` / Promise,解析為 `IDepsResult` 欄位加上 `name` 與 `value`
|
|
73
|
+
|
|
74
|
+
### `queryDepsValueByNpaResult(depsResult, options?: IOptions)`
|
|
75
|
+
|
|
76
|
+
針對既有的依賴值轉換結果執行版本查詢,僅回傳 `{ name, value }`。
|
|
77
|
+
Runs the version query for an existing dependency value conversion result, returning only `{ name, value }`.
|
|
78
|
+
|
|
79
|
+
**Parameters / 參數:**
|
|
80
|
+
- `depsResult` - `IDepsResult` or a promise of it / `IDepsResult` 或其 Promise
|
|
81
|
+
- `options` - Query options / 查詢選項
|
|
82
|
+
|
|
83
|
+
**Returns / 回傳:**
|
|
84
|
+
- `{ name: string, value: string }` - `value` 為 `operator` 加上查詢到的版本或原始範圍 / `value` is the `operator` plus the queried version or the original range
|
|
85
|
+
|
|
86
|
+
## Configuration / 設定
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
export interface IOptions extends IOptionsDepsValue
|
|
90
|
+
{
|
|
91
|
+
queryOptions?: IOptionsQueryVersion<Options>,
|
|
58
92
|
}
|
|
59
|
-
|
|
60
|
-
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
- `queryOptions` - 傳給 `@yarn-tool/pkg-version-query` 的查詢選項,內含 `package-json` 的 `Options`(例如自訂 registry 或請求設定)
|
|
96
|
+
/ Query options passed to `@yarn-tool/pkg-version-query`, including `package-json` `Options` (e.g. custom registry or request settings)
|
|
97
|
+
- `where` - 解析相對路徑的基礎目錄(由 `npaToDepsValue` 使用)
|
|
98
|
+
/ Base directory for resolving relative paths (used by `npaToDepsValue`)
|
|
99
|
+
- `preserveTag` / `preserveRange` - 沿用 `@yarn-tool/npa-to-deps` 的選項;`npaToDepsValue` 目前僅使用 `where`
|
|
100
|
+
/ Inherited from `@yarn-tool/npa-to-deps`; `npaToDepsValue` currently only uses `where`
|
|
101
|
+
|
|
102
|
+
## Related / 相關專案
|
|
103
|
+
|
|
104
|
+
- [@yarn-tool/npa-to-deps](../npa-to-deps) - Convert npm-package-arg results to dependency values / 將 npm-package-arg 結果轉換為依賴值
|
|
105
|
+
- [@yarn-tool/pkg-version-query](../pkg-version-query) - Query package versions from the npm registry / 從 npm registry 查詢套件版本
|
|
106
|
+
- [npm-package-arg 特殊輸入狀況說明](../../../docs/npm-package-arg-special-cases.md) - Special input cases (empty string, space, `*`) and how they are detected / npm-package-arg 特殊輸入(空字串、空格、`*`)的行為與偵測方式
|
package/index.d.ts
CHANGED
|
@@ -1,16 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Resolve npm-package-arg specs to concrete versions via the npm registry
|
|
3
|
+
* @description 透過 npm registry 將 npm-package-arg (npa) 規格解析為具體版本
|
|
4
|
+
*
|
|
5
|
+
* 設計重點:只有轉換結果標記 fetchQuery 時才發送 registry 請求,
|
|
6
|
+
* 可直接保留的範圍或標籤原樣回傳,避免不必要的網路查詢。
|
|
7
|
+
*
|
|
8
|
+
* Design note: a registry request is sent only when the conversion result is flagged
|
|
9
|
+
* `fetchQuery`; ranges or tags that can be kept as-is are returned without any lookup.
|
|
10
|
+
*
|
|
11
|
+
* @module @yarn-tool/npa-to-deps-query
|
|
12
|
+
*/
|
|
1
13
|
import { IOptions as IOptionsDepsValue, IDepsResult } from '@yarn-tool/npa-to-deps';
|
|
2
14
|
import Bluebird from 'bluebird';
|
|
3
15
|
import { ITSResolvable } from 'ts-type';
|
|
4
16
|
import { IOptionsQueryVersion } from '@yarn-tool/pkg-version-query/lib/types';
|
|
5
17
|
import { Options } from 'package-json';
|
|
6
18
|
import { IResult } from '@yarn-tool/npm-package-arg-util/lib/types';
|
|
19
|
+
/**
|
|
20
|
+
* 解析、轉換與查詢共用的選項 / Options shared by parsing, conversion and query
|
|
21
|
+
*
|
|
22
|
+
* 繼承 @yarn-tool/npa-to-deps 的解析選項,再加上 registry 查詢專用的 queryOptions
|
|
23
|
+
* Extends the parsing options of @yarn-tool/npa-to-deps with the registry-specific `queryOptions`
|
|
24
|
+
*
|
|
25
|
+
* @export
|
|
26
|
+
* @interface IOptions
|
|
27
|
+
*/
|
|
7
28
|
export interface IOptions extends IOptionsDepsValue {
|
|
29
|
+
/**
|
|
30
|
+
* 傳給 @yarn-tool/pkg-version-query 的查詢選項,可用來覆寫 package-json 的請求設定
|
|
31
|
+
* Query options forwarded to @yarn-tool/pkg-version-query, e.g. to override package-json request settings
|
|
32
|
+
*/
|
|
8
33
|
queryOptions?: IOptionsQueryVersion<Options>;
|
|
9
34
|
}
|
|
35
|
+
/**
|
|
36
|
+
* 針對既有的依賴值轉換結果查詢版本 / Query a version for an existing dependency value result
|
|
37
|
+
*
|
|
38
|
+
* 當結果標記 fetchQuery 時,以 semver(缺漏時退回 fetchSpec)向 registry 查詢符合的版本;
|
|
39
|
+
* 否則直接以原始 semver 組出 value,不發送任何請求。
|
|
40
|
+
*
|
|
41
|
+
* When the result is flagged `fetchQuery`, query the registry for a matching version using
|
|
42
|
+
* `semver` (falling back to `fetchSpec` when it is absent); otherwise compose `value` from the
|
|
43
|
+
* original `semver` without any request.
|
|
44
|
+
*
|
|
45
|
+
* @param {ITSResolvable<IDepsResult>} depsResult - 依賴值轉換結果或其 Promise / dependency value result or a promise of it
|
|
46
|
+
*
|
|
47
|
+
* @param {IOptions} [options] - 查詢與轉換選項 / query and conversion options
|
|
48
|
+
*
|
|
49
|
+
* @returns {{ name: string, value: string }} value 為 operator 加上版本或原始範圍 / value is the operator plus the queried version or the original range
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* await queryDepsValueByNpaResult(npaToDepsValue('jest@^12'));
|
|
53
|
+
* // => { name: 'jest', value: '^12.1.1' }
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* await queryDepsValueByNpaResult(npaToDepsValue('jest@>12'));
|
|
57
|
+
* // => { name: 'jest', value: '>12' }(無需查詢 / no lookup needed)
|
|
58
|
+
*/
|
|
10
59
|
export declare function queryDepsValueByNpaResult(depsResult: ITSResolvable<IDepsResult>, options?: IOptions): Bluebird<{
|
|
11
60
|
name: string;
|
|
12
61
|
value: string;
|
|
13
62
|
}>;
|
|
63
|
+
/**
|
|
64
|
+
* 解析套件規格字串並查詢具體版本 / Parse a package spec string and query the concrete version
|
|
65
|
+
*
|
|
66
|
+
* 先以 npaToDepsValue 解析 input,再交給 queryDepsValueByNpaResult 查詢版本,
|
|
67
|
+
* 最後把轉換結果與 { name, value } 合併回傳,讓呼叫端一次取得完整依賴資訊。
|
|
68
|
+
*
|
|
69
|
+
* Parse `input` with npaToDepsValue, run the lookup through queryDepsValueByNpaResult,
|
|
70
|
+
* then merge the conversion result with `{ name, value }` so callers get the full
|
|
71
|
+
* dependency information in one place.
|
|
72
|
+
*
|
|
73
|
+
* @param {string} input - 套件規格字串,例如 `jest@^12` / package spec string, e.g. `jest@^12`
|
|
74
|
+
*
|
|
75
|
+
* @param {IOptions} [options] - 解析、轉換與查詢選項 / parsing, conversion and query options
|
|
76
|
+
*
|
|
77
|
+
* @example
|
|
78
|
+
* // 查詢 registry 取得具體版本 / Query the registry for a concrete version
|
|
79
|
+
* queryDepsValueByNpa('jest@12').tap(console.dir);
|
|
80
|
+
* // => { name: 'jest', value: '12.1.1', ..., result: ... }
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* // 已有轉換結果時請改用 queryDepsValueByNpaResult
|
|
84
|
+
* // Use queryDepsValueByNpaResult when you already have a conversion result
|
|
85
|
+
* queryDepsValueByNpaResult(npaToDepsValue('jest@>12'));
|
|
86
|
+
* // => { name: 'jest', value: '>12' }
|
|
87
|
+
*/
|
|
14
88
|
export declare function queryDepsValueByNpa(input: string, options?: IOptions): Bluebird<IDepsResult<IResult> & {
|
|
15
89
|
name: string;
|
|
16
90
|
value: string;
|
package/index.js
CHANGED
|
@@ -1,4 +1,16 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @fileoverview Resolve npm-package-arg specs to concrete versions via the npm registry
|
|
4
|
+
* @description 透過 npm registry 將 npm-package-arg (npa) 規格解析為具體版本
|
|
5
|
+
*
|
|
6
|
+
* 設計重點:只有轉換結果標記 fetchQuery 時才發送 registry 請求,
|
|
7
|
+
* 可直接保留的範圍或標籤原樣回傳,避免不必要的網路查詢。
|
|
8
|
+
*
|
|
9
|
+
* Design note: a registry request is sent only when the conversion result is flagged
|
|
10
|
+
* `fetchQuery`; ranges or tags that can be kept as-is are returned without any lookup.
|
|
11
|
+
*
|
|
12
|
+
* @module @yarn-tool/npa-to-deps-query
|
|
13
|
+
*/
|
|
2
14
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
15
|
exports.queryDepsValueByNpaResult = queryDepsValueByNpaResult;
|
|
4
16
|
exports.queryDepsValueByNpa = queryDepsValueByNpa;
|
|
@@ -6,33 +18,128 @@ const tslib_1 = require("tslib");
|
|
|
6
18
|
const npa_to_deps_1 = require("@yarn-tool/npa-to-deps");
|
|
7
19
|
const bluebird_1 = tslib_1.__importDefault(require("bluebird"));
|
|
8
20
|
const queryVersion_1 = require("@yarn-tool/pkg-version-query/lib/queryVersion");
|
|
21
|
+
/**
|
|
22
|
+
* 針對既有的依賴值轉換結果查詢版本 / Query a version for an existing dependency value result
|
|
23
|
+
*
|
|
24
|
+
* 當結果標記 fetchQuery 時,以 semver(缺漏時退回 fetchSpec)向 registry 查詢符合的版本;
|
|
25
|
+
* 否則直接以原始 semver 組出 value,不發送任何請求。
|
|
26
|
+
*
|
|
27
|
+
* When the result is flagged `fetchQuery`, query the registry for a matching version using
|
|
28
|
+
* `semver` (falling back to `fetchSpec` when it is absent); otherwise compose `value` from the
|
|
29
|
+
* original `semver` without any request.
|
|
30
|
+
*
|
|
31
|
+
* @param {ITSResolvable<IDepsResult>} depsResult - 依賴值轉換結果或其 Promise / dependency value result or a promise of it
|
|
32
|
+
*
|
|
33
|
+
* @param {IOptions} [options] - 查詢與轉換選項 / query and conversion options
|
|
34
|
+
*
|
|
35
|
+
* @returns {{ name: string, value: string }} value 為 operator 加上版本或原始範圍 / value is the operator plus the queried version or the original range
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* await queryDepsValueByNpaResult(npaToDepsValue('jest@^12'));
|
|
39
|
+
* // => { name: 'jest', value: '^12.1.1' }
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* await queryDepsValueByNpaResult(npaToDepsValue('jest@>12'));
|
|
43
|
+
* // => { name: 'jest', value: '>12' }(無需查詢 / no lookup needed)
|
|
44
|
+
*/
|
|
9
45
|
function queryDepsValueByNpaResult(depsResult, options) {
|
|
46
|
+
/**
|
|
47
|
+
* 以 Bluebird.resolve() 接受同步值與各種 thenable,讓呼叫端不必區分輸入是值還是 Promise
|
|
48
|
+
* Bluebird.resolve() accepts plain values and any thenable, so callers need not distinguish values from promises
|
|
49
|
+
*/
|
|
10
50
|
return bluebird_1.default.resolve(depsResult)
|
|
11
51
|
.then(depsResult => {
|
|
12
52
|
var _a, _b;
|
|
13
53
|
const name = depsResult.name;
|
|
54
|
+
/**
|
|
55
|
+
* operator 缺漏時以空字串代替,組出的 value 才不會混入 "undefined" 字樣
|
|
56
|
+
* Default a missing operator to an empty string so the composed value never contains "undefined"
|
|
57
|
+
*/
|
|
14
58
|
const operator = (_a = depsResult.operator) !== null && _a !== void 0 ? _a : '';
|
|
59
|
+
/**
|
|
60
|
+
* fetchQuery 表示 npa-to-deps 無法自行決定版本(例如 ^12、未帶運算子的 "12"、
|
|
61
|
+
* 標籤如 latest、或空輸入規格),必須向 registry 查詢;未標記者多半是可直接
|
|
62
|
+
* 保留的範圍(如 >12、<12),保留原值可避免多餘的請求
|
|
63
|
+
*
|
|
64
|
+
* `fetchQuery` means npa-to-deps cannot decide the version by itself (e.g. `^12`,
|
|
65
|
+
* the bare `12`, a tag like `latest`, or an empty input spec), so the registry must
|
|
66
|
+
* be asked; unflagged results are usually ranges kept as-is (e.g. `>12`, `<12`),
|
|
67
|
+
* which avoids an unnecessary request
|
|
68
|
+
*/
|
|
15
69
|
if (depsResult.fetchQuery) {
|
|
70
|
+
/**
|
|
71
|
+
* semver 缺漏時(例如空輸入規格)退回 fetchSpec(如 "*"),確保查詢仍有依據
|
|
72
|
+
* When `semver` is missing (e.g. an empty input spec), fall back to `fetchSpec`
|
|
73
|
+
* (e.g. "*") so the lookup still has a basis
|
|
74
|
+
*/
|
|
16
75
|
return (0, queryVersion_1.queryVersionWithCache)(depsResult.name, (_b = depsResult.semver) !== null && _b !== void 0 ? _b : depsResult.result.fetchSpec, options === null || options === void 0 ? void 0 : options.queryOptions)
|
|
17
76
|
.then(version => {
|
|
77
|
+
/**
|
|
78
|
+
* 把 operator(如 ^)接回查到的版本,讓 value 可直接寫入 package.json
|
|
79
|
+
* Re-attach the operator (e.g. `^`) to the queried version so the value can be written to package.json directly
|
|
80
|
+
*/
|
|
18
81
|
return {
|
|
19
82
|
name,
|
|
20
83
|
value: `${operator}${version}`,
|
|
21
84
|
};
|
|
22
85
|
});
|
|
23
86
|
}
|
|
87
|
+
/**
|
|
88
|
+
* 不需查詢:operator 加上原始 semver 即為最終 value
|
|
89
|
+
* No lookup needed: operator plus the original `semver` is the final value
|
|
90
|
+
*/
|
|
24
91
|
return {
|
|
25
92
|
name,
|
|
26
93
|
value: `${operator}${depsResult.semver}`,
|
|
27
94
|
};
|
|
28
95
|
});
|
|
29
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* 解析套件規格字串並查詢具體版本 / Parse a package spec string and query the concrete version
|
|
99
|
+
*
|
|
100
|
+
* 先以 npaToDepsValue 解析 input,再交給 queryDepsValueByNpaResult 查詢版本,
|
|
101
|
+
* 最後把轉換結果與 { name, value } 合併回傳,讓呼叫端一次取得完整依賴資訊。
|
|
102
|
+
*
|
|
103
|
+
* Parse `input` with npaToDepsValue, run the lookup through queryDepsValueByNpaResult,
|
|
104
|
+
* then merge the conversion result with `{ name, value }` so callers get the full
|
|
105
|
+
* dependency information in one place.
|
|
106
|
+
*
|
|
107
|
+
* @param {string} input - 套件規格字串,例如 `jest@^12` / package spec string, e.g. `jest@^12`
|
|
108
|
+
*
|
|
109
|
+
* @param {IOptions} [options] - 解析、轉換與查詢選項 / parsing, conversion and query options
|
|
110
|
+
*
|
|
111
|
+
* @example
|
|
112
|
+
* // 查詢 registry 取得具體版本 / Query the registry for a concrete version
|
|
113
|
+
* queryDepsValueByNpa('jest@12').tap(console.dir);
|
|
114
|
+
* // => { name: 'jest', value: '12.1.1', ..., result: ... }
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* // 已有轉換結果時請改用 queryDepsValueByNpaResult
|
|
118
|
+
* // Use queryDepsValueByNpaResult when you already have a conversion result
|
|
119
|
+
* queryDepsValueByNpaResult(npaToDepsValue('jest@>12'));
|
|
120
|
+
* // => { name: 'jest', value: '>12' }
|
|
121
|
+
*/
|
|
30
122
|
function queryDepsValueByNpa(input, options) {
|
|
123
|
+
/**
|
|
124
|
+
* 刻意把同步的 npaToDepsValue 包進 .then(),讓解析階段拋出的同步錯誤
|
|
125
|
+
* 也轉成 promise rejection,呼叫端只需處理一種失敗形式
|
|
126
|
+
*
|
|
127
|
+
* Wrapping the synchronous npaToDepsValue in `.then()` turns synchronous parse errors
|
|
128
|
+
* into promise rejections, so callers only ever handle one failure mode
|
|
129
|
+
*/
|
|
31
130
|
return bluebird_1.default.resolve()
|
|
32
131
|
.then(() => {
|
|
33
132
|
return (0, npa_to_deps_1.npaToDepsValue)(input, options);
|
|
34
133
|
})
|
|
35
134
|
.then((result) => {
|
|
135
|
+
/**
|
|
136
|
+
* 以展開合併:ret 覆寫 name 與 value,其餘 npa 轉換欄位(semver、operator、result 等)
|
|
137
|
+
* 全部保留;型別斷言則標示出合併後新增的 value 欄位
|
|
138
|
+
*
|
|
139
|
+
* Merge by spreading: `ret` overwrites `name` and `value` while the other npa fields
|
|
140
|
+
* (semver, operator, result, ...) are kept; the type assertion marks the `value`
|
|
141
|
+
* field added by the merge
|
|
142
|
+
*/
|
|
36
143
|
return queryDepsValueByNpaResult(result, options)
|
|
37
144
|
.then((ret) => {
|
|
38
145
|
return {
|
package/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAyDH,8DAyDC;AA2BD,kDAmCC;;AA9KD,wDAKgC;AAChC,gEAAgC;AAEhC,gFAAsF;AAuBtF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,yBAAyB,CAAC,UAAsC,EAAE,OAAkB;IAEnG;;;OAGG;IACH,OAAO,kBAAQ,CAAC,OAAO,CAAC,UAAU,CAAC;SACjC,IAAI,CAAC,UAAU,CAAC,EAAE;;QAElB,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAE7B;;;WAGG;QACH,MAAM,QAAQ,GAAG,MAAA,UAAU,CAAC,QAAQ,mCAAI,EAAE,CAAC;QAE3C;;;;;;;;;WASG;QACH,IAAI,UAAU,CAAC,UAAU,EACzB,CAAC;YACA;;;;eAIG;YACH,OAAO,IAAA,oCAAqB,EAAC,UAAU,CAAC,IAAI,EAAE,MAAA,UAAU,CAAC,MAAM,mCAAI,UAAU,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,YAAY,CAAC;iBACpH,IAAI,CAAC,OAAO,CAAC,EAAE;gBAEf;;;mBAGG;gBACH,OAAO;oBACN,IAAI;oBACJ,KAAK,EAAE,GAAG,QAAQ,GAAG,OAAO,EAAE;iBAC9B,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;QAED;;;WAGG;QACH,OAAO;YACN,IAAI;YACJ,KAAK,EAAE,GAAG,QAAQ,GAAG,UAAU,CAAC,MAAM,EAAE;SACxC,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,mBAAmB,CAAC,KAAa,EAAE,OAAkB;IAEpE;;;;;;OAMG;IACH,OAAO,kBAAQ,CAAC,OAAO,EAAE;SACvB,IAAI,CAAC,GAAG,EAAE;QAEV,OAAO,IAAA,4BAAc,EAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACtC,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QAEhB;;;;;;;WAOG;QACH,OAAO,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAAC;aAC/C,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;YACb,OAAO;gBACN,GAAG,MAAM;gBACT,GAAG,GAAG;aAIN,CAAA;QACF,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,kBAAe,mBAAmB,CAAA","sourcesContent":["/**\n * @fileoverview Resolve npm-package-arg specs to concrete versions via the npm registry\n * @description 透過 npm registry 將 npm-package-arg (npa) 規格解析為具體版本\n *\n * 設計重點:只有轉換結果標記 fetchQuery 時才發送 registry 請求,\n * 可直接保留的範圍或標籤原樣回傳,避免不必要的網路查詢。\n *\n * Design note: a registry request is sent only when the conversion result is flagged\n * `fetchQuery`; ranges or tags that can be kept as-is are returned without any lookup.\n *\n * @module @yarn-tool/npa-to-deps-query\n */\n\nimport {\n\tnpaToDepsValue,\n\tnpaResultToDepsValue,\n\tIOptions as IOptionsDepsValue,\n\tIDepsResult,\n} from '@yarn-tool/npa-to-deps';\nimport Bluebird from 'bluebird';\nimport { ITSResolvable } from 'ts-type';\nimport { queryVersionWithCache } from '@yarn-tool/pkg-version-query/lib/queryVersion';\nimport { IOptionsQueryVersion } from '@yarn-tool/pkg-version-query/lib/types';\nimport { Options } from 'package-json';\nimport { IResult } from '@yarn-tool/npm-package-arg-util/lib/types';\n\n/**\n * 解析、轉換與查詢共用的選項 / Options shared by parsing, conversion and query\n *\n * 繼承 @yarn-tool/npa-to-deps 的解析選項,再加上 registry 查詢專用的 queryOptions\n * Extends the parsing options of @yarn-tool/npa-to-deps with the registry-specific `queryOptions`\n *\n * @export\n * @interface IOptions\n */\nexport interface IOptions extends IOptionsDepsValue\n{\n\t/**\n\t * 傳給 @yarn-tool/pkg-version-query 的查詢選項,可用來覆寫 package-json 的請求設定\n\t * Query options forwarded to @yarn-tool/pkg-version-query, e.g. to override package-json request settings\n\t */\n\tqueryOptions?: IOptionsQueryVersion<Options>,\n}\n\n/**\n * 針對既有的依賴值轉換結果查詢版本 / Query a version for an existing dependency value result\n *\n * 當結果標記 fetchQuery 時,以 semver(缺漏時退回 fetchSpec)向 registry 查詢符合的版本;\n * 否則直接以原始 semver 組出 value,不發送任何請求。\n *\n * When the result is flagged `fetchQuery`, query the registry for a matching version using\n * `semver` (falling back to `fetchSpec` when it is absent); otherwise compose `value` from the\n * original `semver` without any request.\n *\n * @param {ITSResolvable<IDepsResult>} depsResult - 依賴值轉換結果或其 Promise / dependency value result or a promise of it\n *\n * @param {IOptions} [options] - 查詢與轉換選項 / query and conversion options\n *\n * @returns {{ name: string, value: string }} value 為 operator 加上版本或原始範圍 / value is the operator plus the queried version or the original range\n *\n * @example\n * await queryDepsValueByNpaResult(npaToDepsValue('jest@^12'));\n * // => { name: 'jest', value: '^12.1.1' }\n *\n * @example\n * await queryDepsValueByNpaResult(npaToDepsValue('jest@>12'));\n * // => { name: 'jest', value: '>12' }(無需查詢 / no lookup needed)\n */\nexport function queryDepsValueByNpaResult(depsResult: ITSResolvable<IDepsResult>, options?: IOptions)\n{\n\t/**\n\t * 以 Bluebird.resolve() 接受同步值與各種 thenable,讓呼叫端不必區分輸入是值還是 Promise\n\t * Bluebird.resolve() accepts plain values and any thenable, so callers need not distinguish values from promises\n\t */\n\treturn Bluebird.resolve(depsResult)\n\t\t.then(depsResult =>\n\t\t{\n\t\t\tconst name = depsResult.name;\n\n\t\t\t/**\n\t\t\t * operator 缺漏時以空字串代替,組出的 value 才不會混入 \"undefined\" 字樣\n\t\t\t * Default a missing operator to an empty string so the composed value never contains \"undefined\"\n\t\t\t */\n\t\t\tconst operator = depsResult.operator ?? '';\n\n\t\t\t/**\n\t\t\t * fetchQuery 表示 npa-to-deps 無法自行決定版本(例如 ^12、未帶運算子的 \"12\"、\n\t\t\t * 標籤如 latest、或空輸入規格),必須向 registry 查詢;未標記者多半是可直接\n\t\t\t * 保留的範圍(如 >12、<12),保留原值可避免多餘的請求\n\t\t\t *\n\t\t\t * `fetchQuery` means npa-to-deps cannot decide the version by itself (e.g. `^12`,\n\t\t\t * the bare `12`, a tag like `latest`, or an empty input spec), so the registry must\n\t\t\t * be asked; unflagged results are usually ranges kept as-is (e.g. `>12`, `<12`),\n\t\t\t * which avoids an unnecessary request\n\t\t\t */\n\t\t\tif (depsResult.fetchQuery)\n\t\t\t{\n\t\t\t\t/**\n\t\t\t\t * semver 缺漏時(例如空輸入規格)退回 fetchSpec(如 \"*\"),確保查詢仍有依據\n\t\t\t\t * When `semver` is missing (e.g. an empty input spec), fall back to `fetchSpec`\n\t\t\t\t * (e.g. \"*\") so the lookup still has a basis\n\t\t\t\t */\n\t\t\t\treturn queryVersionWithCache(depsResult.name, depsResult.semver ?? depsResult.result.fetchSpec, options?.queryOptions)\n\t\t\t\t\t.then(version =>\n\t\t\t\t\t{\n\t\t\t\t\t\t/**\n\t\t\t\t\t\t * 把 operator(如 ^)接回查到的版本,讓 value 可直接寫入 package.json\n\t\t\t\t\t\t * Re-attach the operator (e.g. `^`) to the queried version so the value can be written to package.json directly\n\t\t\t\t\t\t */\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tname,\n\t\t\t\t\t\t\tvalue: `${operator}${version}`,\n\t\t\t\t\t\t};\n\t\t\t\t\t})\n\t\t\t}\n\n\t\t\t/**\n\t\t\t * 不需查詢:operator 加上原始 semver 即為最終 value\n\t\t\t * No lookup needed: operator plus the original `semver` is the final value\n\t\t\t */\n\t\t\treturn {\n\t\t\t\tname,\n\t\t\t\tvalue: `${operator}${depsResult.semver}`,\n\t\t\t};\n\t\t})\n}\n\n/**\n * 解析套件規格字串並查詢具體版本 / Parse a package spec string and query the concrete version\n *\n * 先以 npaToDepsValue 解析 input,再交給 queryDepsValueByNpaResult 查詢版本,\n * 最後把轉換結果與 { name, value } 合併回傳,讓呼叫端一次取得完整依賴資訊。\n *\n * Parse `input` with npaToDepsValue, run the lookup through queryDepsValueByNpaResult,\n * then merge the conversion result with `{ name, value }` so callers get the full\n * dependency information in one place.\n *\n * @param {string} input - 套件規格字串,例如 `jest@^12` / package spec string, e.g. `jest@^12`\n *\n * @param {IOptions} [options] - 解析、轉換與查詢選項 / parsing, conversion and query options\n *\n * @example\n * // 查詢 registry 取得具體版本 / Query the registry for a concrete version\n * queryDepsValueByNpa('jest@12').tap(console.dir);\n * // => { name: 'jest', value: '12.1.1', ..., result: ... }\n *\n * @example\n * // 已有轉換結果時請改用 queryDepsValueByNpaResult\n * // Use queryDepsValueByNpaResult when you already have a conversion result\n * queryDepsValueByNpaResult(npaToDepsValue('jest@>12'));\n * // => { name: 'jest', value: '>12' }\n */\nexport function queryDepsValueByNpa(input: string, options?: IOptions)\n{\n\t/**\n\t * 刻意把同步的 npaToDepsValue 包進 .then(),讓解析階段拋出的同步錯誤\n\t * 也轉成 promise rejection,呼叫端只需處理一種失敗形式\n\t *\n\t * Wrapping the synchronous npaToDepsValue in `.then()` turns synchronous parse errors\n\t * into promise rejections, so callers only ever handle one failure mode\n\t */\n\treturn Bluebird.resolve()\n\t\t.then(() =>\n\t\t{\n\t\t\treturn npaToDepsValue(input, options)\n\t\t})\n\t\t.then((result) =>\n\t\t{\n\t\t\t/**\n\t\t\t * 以展開合併:ret 覆寫 name 與 value,其餘 npa 轉換欄位(semver、operator、result 等)\n\t\t\t * 全部保留;型別斷言則標示出合併後新增的 value 欄位\n\t\t\t *\n\t\t\t * Merge by spreading: `ret` overwrites `name` and `value` while the other npa fields\n\t\t\t * (semver, operator, result, ...) are kept; the type assertion marks the `value`\n\t\t\t * field added by the merge\n\t\t\t */\n\t\t\treturn queryDepsValueByNpaResult(result, options)\n\t\t\t\t.then((ret) => {\n\t\t\t\t\treturn {\n\t\t\t\t\t\t...result,\n\t\t\t\t\t\t...ret,\n\t\t\t\t\t} as IDepsResult<IResult> & {\n\t\t\t\t\t\tname: string,\n\t\t\t\t\t\tvalue: string,\n\t\t\t\t\t}\n\t\t\t\t})\n\t\t})\n}\n\nexport default queryDepsValueByNpa\n"]}
|
package/package.json
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yarn-tool/npa-to-deps-query",
|
|
3
|
-
"version": "3.0.
|
|
4
|
-
"description": "",
|
|
3
|
+
"version": "3.0.12",
|
|
4
|
+
"description": "Resolve npm-package-arg specs to concrete versions by querying the npm registry / 透過查詢 npm registry 將 npm-package-arg 規格解析為具體版本",
|
|
5
5
|
"keywords": [
|
|
6
|
+
"npm-package-arg",
|
|
7
|
+
"npa",
|
|
8
|
+
"version-query",
|
|
9
|
+
"registry",
|
|
10
|
+
"query",
|
|
6
11
|
"yarn",
|
|
7
12
|
"yarn-tool",
|
|
8
13
|
"npm",
|
|
@@ -31,12 +36,14 @@
|
|
|
31
36
|
"scripts": {
|
|
32
37
|
"coverage": "pnpm run test -- --coverage",
|
|
33
38
|
"lint": "ynpx --quiet eslint -- **/*.ts",
|
|
34
|
-
"test": "
|
|
39
|
+
"test": "node --run test:node",
|
|
35
40
|
"test:jest": "jest --passWithNoTests",
|
|
36
41
|
"test:jest:coverage": "pnpm run test:jest -- --coverage",
|
|
37
42
|
"test:jest:snapshot": "pnpm run test:jest -- -u",
|
|
38
43
|
"test:mocha": "ynpx --quiet -p ts-node -p mocha mocha -- --require ts-node/register \"!(node_modules)/**/*.{test,spec}.{ts,tsx}\"",
|
|
44
|
+
"test:node": "tsx --test --test-update-snapshots **/*.node-spec.ts **/*.node-test.ts **/*.spec.ts **/*.test.ts",
|
|
39
45
|
"test:snapshot": "pnpm run test -u",
|
|
46
|
+
"test:tsc": "tsc --noEmit & echo typescript check done",
|
|
40
47
|
"test:tsd": "ynpx tsd",
|
|
41
48
|
"preversion": "echo preversion && pnpm run test",
|
|
42
49
|
"version": "echo version",
|
|
@@ -52,16 +59,16 @@
|
|
|
52
59
|
"tsc:showConfig": "ynpx get-current-tsconfig -p"
|
|
53
60
|
},
|
|
54
61
|
"dependencies": {
|
|
55
|
-
"@yarn-tool/npa-to-deps": "^3.0.
|
|
56
|
-
"@yarn-tool/npm-package-arg-util": "^2.0.
|
|
57
|
-
"@yarn-tool/pkg-version-query": "^3.0.
|
|
62
|
+
"@yarn-tool/npa-to-deps": "^3.0.10",
|
|
63
|
+
"@yarn-tool/npm-package-arg-util": "^2.0.10",
|
|
64
|
+
"@yarn-tool/pkg-version-query": "^3.0.12",
|
|
58
65
|
"bluebird": "^3.7.2",
|
|
59
66
|
"package-json": "<7 >=6.5",
|
|
60
|
-
"ts-type": "^3.0.
|
|
67
|
+
"ts-type": "^3.0.18",
|
|
61
68
|
"tslib": ">=2.8.1"
|
|
62
69
|
},
|
|
63
70
|
"publishConfig": {
|
|
64
71
|
"access": "public"
|
|
65
72
|
},
|
|
66
|
-
"gitHead": "
|
|
73
|
+
"gitHead": "cf2f309300d7e01680c5b8bd91114fe16dbadb24"
|
|
67
74
|
}
|