1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
# npm-pick-manifest [](https://npm.im/npm-pick-manifest) [](https://npm.im/npm-pick-manifest) [](https://travis-ci.org/npm/npm-pick-manifest) [](https://coveralls.io/github/npm/npm-pick-manifest?branch=latest)
[`npm-pick-manifest`](https://github.com/npm/npm-pick-manifest) is a standalone
implementation of [npm](https://npmjs.com)'s semver range resolution algorithm.
## Install
`$ npm install --save npm-pick-manifest`
## Table of Contents
* [Example](#example)
* [Features](#features)
* [API](#api)
* [`pickManifest()`](#pick-manifest)
### Example
```javascript
const pickManifest = require('npm-pick-manifest')
fetch('https://registry.npmjs.org/npm-pick-manifest').then(res => {
return res.json()
}).then(packument => {
return pickManifest(packument, '^1.0.0')
}) // get same manifest as npm would get if you `npm i npm-pick-manifest@^1.0.0`
```
### Features
* Uses npm's exact [semver resolution algorithm](http://npm.im/semver).
* Supports ranges, tags, and versions.
* Prefers non-deprecated versions to deprecated versions.
* Prefers versions whose `engines` requirements are satisfied over those
that will raise a warning or error at install time.
### API
#### <a name="pick-manifest"></a> `> pickManifest(packument, selector, [opts]) -> manifest`
Returns the manifest that best matches `selector`, or throws an error.
Packuments are anything returned by metadata URLs from the npm registry. That
is, they're objects with the following shape (only fields used by
`npm-pick-manifest` included):
```javascript
{
name: 'some-package',
'dist-tags': {
foo: '1.0.1'
},
versions: {
'1.0.0': { version: '1.0.0' },
'1.0.1': { version: '1.0.1' },
'1.0.2': { version: '1.0.2' },
'2.0.0': { version: '2.0.0' }
}
}
```
The algorithm will follow npm's algorithm for semver resolution, and only
`tag`, `range`, and `version` selectors are supported.
The function will throw `ETARGET` if there was no matching manifest, and
`ENOVERSIONS` if the packument object has no valid versions in `versions`.
If the only matching manifest is included in a `policyRestrictions` section
of the packument, then an `E403` is raised.
#### <a name="pick-manifest-options"></a> Options
All options are optional.
* `includeStaged` - Boolean, default `false`. Include manifests in the
`stagedVersions.versions` set, to support installing [staged
packages](https://github.com/npm/rfcs/pull/92) when appropriate. Note
that staged packages are always treated as lower priority than actual
publishes, even when `includeStaged` is set.
* `defaultTag` - String, default `'latest'`. The default `dist-tag` to
install when no specifier is provided. Note that the version indicated
by this specifier will be given top priority if it matches a supplied
semver range.
* `before` - String, Date, or Number, default `null`. This is passed to
`new Date()`, so anything that works there will be valid. Do not
consider _any_ manifests that were published after the date indicated.
Note that this is only relevant when the packument includes a `time`
field listing the publish date of all the packages.
* `nodeVersion` - String, default `process.version`. The Node.js version
to use when checking manifests for `engines` requirement satisfaction.
* `npmVersion` - String, default `null`. The npm version to use when
checking manifest for `engines` requirement satisfaction. (If `null`,
then this particular check is skipped.)
* `avoid` - String, default `null`. A SemVer range of
versions that should be avoided. An avoided version MAY be selected if
there is no other option, so when using this for version selection ensure
that you check the result against the range to see if there was no
alternative available.
* `avoidStrict` Boolean, default `false`. If set to true, then
`pickManifest` will never return a version in the `avoid` range. If the
only available version in the `wanted` range is a version that should be
avoided, then it will return a version _outside_ the `wanted` range,
preferring to do so without making a SemVer-major jump, if possible. If
there are no versions outside the `avoid` range, then throw an
`ETARGET` error. It does this by calling pickManifest first with the
`wanted` range, then with a `^` affixed to the version returned by the
`wanted` range, and then with a `*` version range, and throwing if
nothing could be found to satisfy the avoidance request.
Return value is the manifest as it exists in the packument, possibly
decorated with the following boolean flags:
* `_shouldAvoid` The version is in the `avoid` range. Watch out!
* `_outsideDependencyRange` The version is outside the `wanted` range,
because `avoidStrict: true` was set.
* `_isSemVerMajor` The `_outsideDependencyRange` result is a SemVer-major
step up from the version returned by the `wanted` range.
### Algorithm
1. Create list of all versions in `versions`,
`policyRestrictions.versions`, and (if `includeStaged` is set)
`stagedVersions.versions`.
2. If a `dist-tag` is requested,
1. If the manifest is not after the specified `before` date, then
select that from the set.
2. If the manifest is after the specified `before` date, then re-start
the selection looking for the highest SemVer range that is equal to
or less than the `dist-tag` target.
3. If a specific version is requested,
1. If the manifest is not after the specified `before` date, then
select the specified manifest.
2. If the manifest is after the specified `before` date, then raise
`ETARGET` error. (NB: this is a breaking change from v5, where a
specified version would override the `before` setting.)
4. (At this point we know a range is requested.)
5. If the `defaultTag` refers to a `dist-tag` that satisfies the range (or
if the range is `'*'` or `''`), and the manifest is published before the
`before` setting, then select that manifest.
6. If nothing is yet selected, sort by the following heuristics in order,
and select the top item:
1. Prioritize versions that are not in the `avoid` range over those
that are.
2. Prioritize versions that are not in `policyRestrictions` over those
that are.
3. Prioritize published versions over staged versions.
4. Prioritize versions that are not deprecated, and which have a
satisfied engines requirement, over those that are either deprecated
or have an engines mismatch.
5. Prioritize versions that have a satisfied engines requirement over
those that do not.
6. Prioritize versions that are not are not deprecated (but have a
mismatched engines requirement) over those that are deprecated.
7. Prioritize higher SemVer precedence over lower SemVer precedence.
7. If no manifest was selected, raise an `ETARGET` error.
8. If the selected item is in the `policyRestrictions.versions` list, raise
an `E403` error.
9. Return the selected manifest.
|
