npmnpm-pick-manifest 
npm-pick-manifest is a standalone
implementation of npm's semver range resolution algorithm.
Install
$ npm install --save npm-pick-manifest
Table of Contents
Example
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.
- Supports ranges, tags, and versions.
- Prefers non-deprecated versions to deprecated versions.
- Prefers versions whose
enginesrequirements are satisfied over those that will raise a warning or error at install time.
API
> 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):
{
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.
Options
All options are optional.
includeStaged- Boolean, defaultfalse. Include manifests in thestagedVersions.versionsset, to support installing staged packages when appropriate. Note that staged packages are always treated as lower priority than actual publishes, even whenincludeStagedis set.defaultTag- String, default'latest'. The defaultdist-tagto 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, defaultnull. This is passed tonew 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 atimefield listing the publish date of all the packages.nodeVersion- String, defaultprocess.version. The Node.js version to use when checking manifests forenginesrequirement satisfaction.npmVersion- String, defaultnull. The npm version to use when checking manifest forenginesrequirement satisfaction. (Ifnull, then this particular check is skipped.)avoid- String, defaultnull. 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.avoidStrictBoolean, defaultfalse. If set to true, thenpickManifestwill never return a version in theavoidrange. If the only available version in thewantedrange is a version that should be avoided, then it will return a version outside thewantedrange, preferring to do so without making a SemVer-major jump, if possible. If there are no versions outside theavoidrange, then throw anETARGETerror. It does this by calling pickManifest first with thewantedrange, then with a^affixed to the version returned by thewantedrange, 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:
_shouldAvoidThe version is in theavoidrange. Watch out!_outsideDependencyRangeThe version is outside thewantedrange, becauseavoidStrict: truewas set._isSemVerMajorThe_outsideDependencyRangeresult is a SemVer-major step up from the version returned by thewantedrange.
Algorithm
- Create list of all versions in
versions,policyRestrictions.versions, and (ifincludeStagedis set)stagedVersions.versions. - If a
dist-tagis requested,- If the manifest is not after the specified
beforedate, then select that from the set. - If the manifest is after the specified
beforedate, then re-start the selection looking for the highest SemVer range that is equal to or less than thedist-tagtarget.
- If the manifest is not after the specified
- If a specific version is requested,
- If the manifest is not after the specified
beforedate, then select the specified manifest. - If the manifest is after the specified
beforedate, then raiseETARGETerror. (NB: this is a breaking change from v5, where a specified version would override thebeforesetting.)
- If the manifest is not after the specified
- (At this point we know a range is requested.)
- If the
defaultTagrefers to adist-tagthat satisfies the range (or if the range is'*'or''), and the manifest is published before thebeforesetting, then select that manifest. - If nothing is yet selected, sort by the following heuristics in order,
and select the top item:
- Prioritize versions that are not in the
avoidrange over those that are. - Prioritize versions that are not in
policyRestrictionsover those that are. - Prioritize published versions over staged versions.
- Prioritize versions that are not deprecated, and which have a satisfied engines requirement, over those that are either deprecated or have an engines mismatch.
- Prioritize versions that have a satisfied engines requirement over those that do not.
- Prioritize versions that are not are not deprecated (but have a mismatched engines requirement) over those that are deprecated.
- Prioritize higher SemVer precedence over lower SemVer precedence.
- Prioritize versions that are not in the
- If no manifest was selected, raise an
ETARGETerror. - If the selected item is in the
policyRestrictions.versionslist, raise anE403error. - Return the selected manifest.