sfcode: npm-pick-manifest <a href="https://npm.im/npm-pick-manifest"><img src="https://img.shields.io/npm/v/npm-pick-manifest.svg" alt="npm version"/></a> <a href="https://npm.im/npm-pick-manifest"><img src="https://img.shields.io/npm/l/npm-pick-manifest.svg" alt="license"/></a> <a href="https://travis-ci.org/npm/npm-pick-manifest"><img src="https://img.shields.io/travis/npm/npm-pick-manifest.svg" alt="Travis"/></a> <a href="https://coveralls.io/github/npm/npm-pick-manifest?branch=latest"><img src="https://coveralls.io/repos/github/npm/npm-pick-manifest/badge.svg?branch=latest" alt="Coverage Status"/></a>
npm-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
- Features
- API
  - `pickManifest()`

## 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 `engines` requirements are satisfied over those that will raise a warning or error at install time.

## API

### <a name="pick-manifest"></a> <tt>> pickManifest(packument, selector, [opts]) -> manifest</tt>

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.

### <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 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.