Resolves a matching manifest from a package metadata document according to standard npm semver resolution rules.
npm install npm-pick-manifestnpm-pick-manifest is a standalone
implementation of npm's semver range resolution algorithm.
$ npm install --save npm-pick-manifest
* Example
* Features
* API
* pickManifest()
``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`
* Uses npm's exact semver resolution algorithm.
* 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.
#### > 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, andENOVERSIONS if the packument object has no valid versions in versions.policyRestrictions
If the only matching manifest is included in a sectionE403
of the packument, then an is raised.
All options are optional.
* includeStaged - Boolean, default false. Include manifests in thestagedVersions.versions
set, to support installing stagedincludeStaged
packages when appropriate. Note
that staged packages are always treated as lower priority than actual
publishes, even when is set.defaultTag
* - String, default 'latest'. The default dist-tag tobefore
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.
* - String, Date, or Number, default null. This is passed tonew Date()
, so anything that works there will be valid. Do nottime
consider _any_ manifests that were published after the date indicated.
Note that this is only relevant when the packument includes a nodeVersion
field listing the publish date of all the packages.
* - String, default process.version. The Node.js versionengines
to use when checking manifests for requirement satisfaction.npmVersion
* - String, default null. The npm version to use whenengines
checking manifest for requirement satisfaction. (If null,avoid
then this particular check is skipped.)
* - String, default null. A SemVer range ofavoidStrict
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.
* Boolean, default false. If set to true, thenpickManifest
will never return a version in the avoid range. If thewanted
only available version in the range is a version that should bewanted
avoided, then it will return a version _outside_ the range,avoid
preferring to do so without making a SemVer-major jump, if possible. If
there are no versions outside the range, then throw anETARGET
error. It does this by calling pickManifest first with thewanted
range, then with a ^ affixed to the version returned by thewanted
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,avoidStrict: true
because was set._isSemVerMajor
* The _outsideDependencyRange result is a SemVer-majorwanted
step up from the version returned by the range.
1. Create list of all versions in versions,policyRestrictions.versions
, and (if includeStaged is set)stagedVersions.versions
.dist-tag
2. If a is requested,before
1. If the manifest is not after the specified date, thenbefore
select that from the set.
2. If the manifest is after the specified date, then re-startdist-tag
the selection looking for the highest SemVer range that is equal to
or less than the target.before
3. If a specific version is requested,
1. If the manifest is not after the specified date, thenbefore
select the specified manifest.
2. If the manifest is after the specified date, then raiseETARGET
error. (NB: this is a breaking change from v5, where abefore
specified version would override the setting.)defaultTag
4. (At this point we know a range is requested.)
5. If the refers to a dist-tag that satisfies the range (or'*'
if the range is or ''), and the manifest is published before thebefore
setting, then select that manifest.avoid
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 range over thosepolicyRestrictions
that are.
2. Prioritize versions that are not in over thoseETARGET
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 error.policyRestrictions.versions
8. If the selected item is in the list, raiseE403` error.
an
9. Return the selected manifest.