diff options
Diffstat (limited to 'node_modules/npm-pick-manifest/README.md')
| -rw-r--r-- | node_modules/npm-pick-manifest/README.md | 157 |
1 files changed, 0 insertions, 157 deletions
diff --git a/node_modules/npm-pick-manifest/README.md b/node_modules/npm-pick-manifest/README.md deleted file mode 100644 index 26ee43e05..000000000 --- a/node_modules/npm-pick-manifest/README.md +++ /dev/null @@ -1,157 +0,0 @@ -# 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. |