wow
This commit is contained in:
quoije
+250
-27
@@ -4,7 +4,7 @@ semver(1) -- The semantic versioner for npm
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install --save semver
|
||||
npm install semver
|
||||
````
|
||||
|
||||
## Usage
|
||||
@@ -25,6 +25,63 @@ semver.valid(semver.coerce('v2')) // '2.0.0'
|
||||
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
|
||||
```
|
||||
|
||||
You can also just load the module for the function that you care about, if
|
||||
you'd like to minimize your footprint.
|
||||
|
||||
```js
|
||||
// load the whole API at once in a single object
|
||||
const semver = require('semver')
|
||||
|
||||
// or just load the bits you need
|
||||
// all of them listed here, just pick and choose what you want
|
||||
|
||||
// classes
|
||||
const SemVer = require('semver/classes/semver')
|
||||
const Comparator = require('semver/classes/comparator')
|
||||
const Range = require('semver/classes/range')
|
||||
|
||||
// functions for working with versions
|
||||
const semverParse = require('semver/functions/parse')
|
||||
const semverValid = require('semver/functions/valid')
|
||||
const semverClean = require('semver/functions/clean')
|
||||
const semverInc = require('semver/functions/inc')
|
||||
const semverDiff = require('semver/functions/diff')
|
||||
const semverMajor = require('semver/functions/major')
|
||||
const semverMinor = require('semver/functions/minor')
|
||||
const semverPatch = require('semver/functions/patch')
|
||||
const semverPrerelease = require('semver/functions/prerelease')
|
||||
const semverCompare = require('semver/functions/compare')
|
||||
const semverRcompare = require('semver/functions/rcompare')
|
||||
const semverCompareLoose = require('semver/functions/compare-loose')
|
||||
const semverCompareBuild = require('semver/functions/compare-build')
|
||||
const semverSort = require('semver/functions/sort')
|
||||
const semverRsort = require('semver/functions/rsort')
|
||||
|
||||
// low-level comparators between versions
|
||||
const semverGt = require('semver/functions/gt')
|
||||
const semverLt = require('semver/functions/lt')
|
||||
const semverEq = require('semver/functions/eq')
|
||||
const semverNeq = require('semver/functions/neq')
|
||||
const semverGte = require('semver/functions/gte')
|
||||
const semverLte = require('semver/functions/lte')
|
||||
const semverCmp = require('semver/functions/cmp')
|
||||
const semverCoerce = require('semver/functions/coerce')
|
||||
|
||||
// working with ranges
|
||||
const semverSatisfies = require('semver/functions/satisfies')
|
||||
const semverMaxSatisfying = require('semver/ranges/max-satisfying')
|
||||
const semverMinSatisfying = require('semver/ranges/min-satisfying')
|
||||
const semverToComparators = require('semver/ranges/to-comparators')
|
||||
const semverMinVersion = require('semver/ranges/min-version')
|
||||
const semverValidRange = require('semver/ranges/valid')
|
||||
const semverOutside = require('semver/ranges/outside')
|
||||
const semverGtr = require('semver/ranges/gtr')
|
||||
const semverLtr = require('semver/ranges/ltr')
|
||||
const semverIntersects = require('semver/ranges/intersects')
|
||||
const simplifyRange = require('semver/ranges/simplify')
|
||||
const rangeSubset = require('semver/ranges/subset')
|
||||
```
|
||||
|
||||
As a command-line utility:
|
||||
|
||||
```
|
||||
@@ -53,6 +110,9 @@ Options:
|
||||
-l --loose
|
||||
Interpret versions and ranges loosely
|
||||
|
||||
-n <0|1>
|
||||
This is the base to be used for the prerelease identifier.
|
||||
|
||||
-p --include-prerelease
|
||||
Always include prerelease versions in range matching
|
||||
|
||||
@@ -60,6 +120,12 @@ Options:
|
||||
Coerce a string into SemVer if possible
|
||||
(does not imply --loose)
|
||||
|
||||
--rtl
|
||||
Coerce version strings right to left
|
||||
|
||||
--ltr
|
||||
Coerce version strings left to right (default)
|
||||
|
||||
Program exits successfully if any valid version satisfies
|
||||
all supplied ranges, and prints all satisfying versions.
|
||||
|
||||
@@ -169,6 +235,35 @@ $ semver 1.2.4-beta.0 -i prerelease
|
||||
1.2.4-beta.1
|
||||
```
|
||||
|
||||
#### Prerelease Identifier Base
|
||||
|
||||
The method `.inc` takes an optional parameter 'identifierBase' string
|
||||
that will let you let your prerelease number as zero-based or one-based.
|
||||
Set to `false` to omit the prerelease number altogether.
|
||||
If you do not specify this parameter, it will default to zero-based.
|
||||
|
||||
```javascript
|
||||
semver.inc('1.2.3', 'prerelease', 'beta', '1')
|
||||
// '1.2.4-beta.1'
|
||||
```
|
||||
|
||||
```javascript
|
||||
semver.inc('1.2.3', 'prerelease', 'beta', false)
|
||||
// '1.2.4-beta'
|
||||
```
|
||||
|
||||
command-line example:
|
||||
|
||||
```bash
|
||||
$ semver 1.2.3 -i prerelease --preid beta -n 1
|
||||
1.2.4-beta.1
|
||||
```
|
||||
|
||||
```bash
|
||||
$ semver 1.2.3 -i prerelease --preid beta -n false
|
||||
1.2.4-beta
|
||||
```
|
||||
|
||||
### Advanced Range Syntax
|
||||
|
||||
Advanced range syntax desugars to primitive comparators in
|
||||
@@ -193,37 +288,39 @@ inclusive range, then all versions that start with the supplied parts
|
||||
of the tuple are accepted, but nothing that would be greater than the
|
||||
provided tuple parts.
|
||||
|
||||
* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
|
||||
* `1.2.3 - 2` := `>=1.2.3 <3.0.0`
|
||||
* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0-0`
|
||||
* `1.2.3 - 2` := `>=1.2.3 <3.0.0-0`
|
||||
|
||||
#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
|
||||
|
||||
Any of `X`, `x`, or `*` may be used to "stand in" for one of the
|
||||
numeric values in the `[major, minor, patch]` tuple.
|
||||
|
||||
* `*` := `>=0.0.0` (Any version satisfies)
|
||||
* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
|
||||
* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
|
||||
* `*` := `>=0.0.0` (Any non-prerelease version satisfies, unless
|
||||
`includePrerelease` is specified, in which case any version at all
|
||||
satisfies)
|
||||
* `1.x` := `>=1.0.0 <2.0.0-0` (Matching major version)
|
||||
* `1.2.x` := `>=1.2.0 <1.3.0-0` (Matching major and minor versions)
|
||||
|
||||
A partial version range is treated as an X-Range, so the special
|
||||
character is in fact optional.
|
||||
|
||||
* `""` (empty string) := `*` := `>=0.0.0`
|
||||
* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
|
||||
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
|
||||
* `1` := `1.x.x` := `>=1.0.0 <2.0.0-0`
|
||||
* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0-0`
|
||||
|
||||
#### Tilde Ranges `~1.2.3` `~1.2` `~1`
|
||||
|
||||
Allows patch-level changes if a minor version is specified on the
|
||||
comparator. Allows minor-level changes if not.
|
||||
|
||||
* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
|
||||
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
|
||||
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
|
||||
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
|
||||
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
|
||||
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
|
||||
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
|
||||
* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0-0`
|
||||
* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0-0` (Same as `1.2.x`)
|
||||
* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0-0` (Same as `1.x`)
|
||||
* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0-0`
|
||||
* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0-0` (Same as `0.2.x`)
|
||||
* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0-0` (Same as `0.x`)
|
||||
* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0-0` Note that prereleases in
|
||||
the `1.2.3` version will be allowed, if they are greater than or
|
||||
equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
|
||||
`1.2.4-beta.2` would not, because it is a prerelease of a
|
||||
@@ -231,7 +328,7 @@ comparator. Allows minor-level changes if not.
|
||||
|
||||
#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
|
||||
|
||||
Allows changes that do not modify the left-most non-zero digit in the
|
||||
Allows changes that do not modify the left-most non-zero element in the
|
||||
`[major, minor, patch]` tuple. In other words, this allows patch and
|
||||
minor updates for versions `1.0.0` and above, patch updates for
|
||||
versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
|
||||
@@ -245,15 +342,15 @@ However, it presumes that there will *not* be breaking changes between
|
||||
`0.2.4` and `0.2.5`. It allows for changes that are presumed to be
|
||||
additive (but non-breaking), according to commonly observed practices.
|
||||
|
||||
* `^1.2.3` := `>=1.2.3 <2.0.0`
|
||||
* `^0.2.3` := `>=0.2.3 <0.3.0`
|
||||
* `^0.0.3` := `>=0.0.3 <0.0.4`
|
||||
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
|
||||
* `^1.2.3` := `>=1.2.3 <2.0.0-0`
|
||||
* `^0.2.3` := `>=0.2.3 <0.3.0-0`
|
||||
* `^0.0.3` := `>=0.0.3 <0.0.4-0`
|
||||
* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0-0` Note that prereleases in
|
||||
the `1.2.3` version will be allowed, if they are greater than or
|
||||
equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
|
||||
`1.2.4-beta.2` would not, because it is a prerelease of a
|
||||
different `[major, minor, patch]` tuple.
|
||||
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the
|
||||
* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4-0` Note that prereleases in the
|
||||
`0.0.3` version *only* will be allowed, if they are greater than or
|
||||
equal to `beta`. So, `0.0.3-pr.2` would be allowed.
|
||||
|
||||
@@ -261,16 +358,16 @@ When parsing caret ranges, a missing `patch` value desugars to the
|
||||
number `0`, but will allow flexibility within that value, even if the
|
||||
major and minor versions are both `0`.
|
||||
|
||||
* `^1.2.x` := `>=1.2.0 <2.0.0`
|
||||
* `^0.0.x` := `>=0.0.0 <0.1.0`
|
||||
* `^0.0` := `>=0.0.0 <0.1.0`
|
||||
* `^1.2.x` := `>=1.2.0 <2.0.0-0`
|
||||
* `^0.0.x` := `>=0.0.0 <0.1.0-0`
|
||||
* `^0.0` := `>=0.0.0 <0.1.0-0`
|
||||
|
||||
A missing `minor` and `patch` values will desugar to zero, but also
|
||||
allow flexibility within those values, even if the major version is
|
||||
zero.
|
||||
|
||||
* `^1.x` := `>=1.0.0 <2.0.0`
|
||||
* `^0.x` := `>=0.0.0 <1.0.0`
|
||||
* `^1.x` := `>=1.0.0 <2.0.0-0`
|
||||
* `^0.x` := `>=0.0.0 <1.0.0-0`
|
||||
|
||||
### Range Grammar
|
||||
|
||||
@@ -354,6 +451,9 @@ strings that they parse.
|
||||
`v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
|
||||
* `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions
|
||||
in descending order when passed to `Array.sort()`.
|
||||
* `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
|
||||
are equal. Sorts in ascending order if passed to `Array.sort()`.
|
||||
`v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
|
||||
* `diff(v1, v2)`: Returns difference between two versions by the release type
|
||||
(`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
|
||||
or null if the versions are the same.
|
||||
@@ -382,6 +482,16 @@ strings that they parse.
|
||||
`hilo` argument must be either the string `'>'` or `'<'`. (This is
|
||||
the function called by `gtr` and `ltr`.)
|
||||
* `intersects(range)`: Return true if any of the ranges comparators intersect
|
||||
* `simplifyRange(versions, range)`: Return a "simplified" range that
|
||||
matches the same items in `versions` list as the range specified. Note
|
||||
that it does *not* guarantee that it would match the same versions in all
|
||||
cases, only for the set of versions provided. This is useful when
|
||||
generating ranges by joining together multiple versions with `||`
|
||||
programmatically, to provide the user with something a bit more
|
||||
ergonomic. If the provided range is shorter in string-length than the
|
||||
generated range, then that is returned.
|
||||
* `subset(subRange, superRange)`: Return `true` if the `subRange` range is
|
||||
entirely contained by the `superRange` range.
|
||||
|
||||
Note that, since ranges may be non-contiguous, a version might not be
|
||||
greater than a range, less than a range, *or* satisfy a range! For
|
||||
@@ -396,7 +506,7 @@ range, use the `satisfies(version, range)` function.
|
||||
|
||||
### Coercion
|
||||
|
||||
* `coerce(version)`: Coerces a string to semver if possible
|
||||
* `coerce(version, options)`: Coerces a string to semver if possible
|
||||
|
||||
This aims to provide a very forgiving translation of a non-semver string to
|
||||
semver. It looks for the first digit in a string, and consumes all
|
||||
@@ -410,3 +520,116 @@ coercion is 16 characters; longer components will be ignored
|
||||
(`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any
|
||||
semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
|
||||
components are invalid (`9999999999999999.4.7.4` is likely invalid).
|
||||
|
||||
If the `options.rtl` flag is set, then `coerce` will return the right-most
|
||||
coercible tuple that does not share an ending index with a longer coercible
|
||||
tuple. For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
|
||||
`4.0.0`. `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
|
||||
any other overlapping SemVer tuple.
|
||||
|
||||
### Clean
|
||||
|
||||
* `clean(version)`: Clean a string to be a valid semver if possible
|
||||
|
||||
This will return a cleaned and trimmed semver version. If the provided
|
||||
version is not valid a null will be returned. This does not work for
|
||||
ranges.
|
||||
|
||||
ex.
|
||||
* `s.clean(' = v 2.1.5foo')`: `null`
|
||||
* `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
|
||||
* `s.clean(' = v 2.1.5-foo')`: `null`
|
||||
* `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
|
||||
* `s.clean('=v2.1.5')`: `'2.1.5'`
|
||||
* `s.clean(' =v2.1.5')`: `2.1.5`
|
||||
* `s.clean(' 2.1.5 ')`: `'2.1.5'`
|
||||
* `s.clean('~1.0.0')`: `null`
|
||||
|
||||
## Constants
|
||||
|
||||
As a convenience, helper constants are exported to provide information about what `node-semver` supports:
|
||||
|
||||
### `RELEASE_TYPES`
|
||||
|
||||
- major
|
||||
- premajor
|
||||
- minor
|
||||
- preminor
|
||||
- patch
|
||||
- prepatch
|
||||
- prerelease
|
||||
|
||||
```
|
||||
const semver = require('semver');
|
||||
|
||||
if (semver.RELEASE_TYPES.includes(arbitraryUserInput)) {
|
||||
console.log('This is a valid release type!');
|
||||
} else {
|
||||
console.warn('This is NOT a valid release type!');
|
||||
}
|
||||
```
|
||||
|
||||
### `SEMVER_SPEC_VERSION`
|
||||
|
||||
2.0.0
|
||||
|
||||
```
|
||||
const semver = require('semver');
|
||||
|
||||
console.log('We are currently using the semver specification version:', semver.SEMVER_SPEC_VERSION);
|
||||
```
|
||||
|
||||
## Exported Modules
|
||||
|
||||
<!--
|
||||
TODO: Make sure that all of these items are documented (classes aren't,
|
||||
eg), and then pull the module name into the documentation for that specific
|
||||
thing.
|
||||
-->
|
||||
|
||||
You may pull in just the part of this semver utility that you need, if you
|
||||
are sensitive to packing and tree-shaking concerns. The main
|
||||
`require('semver')` export uses getter functions to lazily load the parts
|
||||
of the API that are used.
|
||||
|
||||
The following modules are available:
|
||||
|
||||
* `require('semver')`
|
||||
* `require('semver/classes')`
|
||||
* `require('semver/classes/comparator')`
|
||||
* `require('semver/classes/range')`
|
||||
* `require('semver/classes/semver')`
|
||||
* `require('semver/functions/clean')`
|
||||
* `require('semver/functions/cmp')`
|
||||
* `require('semver/functions/coerce')`
|
||||
* `require('semver/functions/compare')`
|
||||
* `require('semver/functions/compare-build')`
|
||||
* `require('semver/functions/compare-loose')`
|
||||
* `require('semver/functions/diff')`
|
||||
* `require('semver/functions/eq')`
|
||||
* `require('semver/functions/gt')`
|
||||
* `require('semver/functions/gte')`
|
||||
* `require('semver/functions/inc')`
|
||||
* `require('semver/functions/lt')`
|
||||
* `require('semver/functions/lte')`
|
||||
* `require('semver/functions/major')`
|
||||
* `require('semver/functions/minor')`
|
||||
* `require('semver/functions/neq')`
|
||||
* `require('semver/functions/parse')`
|
||||
* `require('semver/functions/patch')`
|
||||
* `require('semver/functions/prerelease')`
|
||||
* `require('semver/functions/rcompare')`
|
||||
* `require('semver/functions/rsort')`
|
||||
* `require('semver/functions/satisfies')`
|
||||
* `require('semver/functions/sort')`
|
||||
* `require('semver/functions/valid')`
|
||||
* `require('semver/ranges/gtr')`
|
||||
* `require('semver/ranges/intersects')`
|
||||
* `require('semver/ranges/ltr')`
|
||||
* `require('semver/ranges/max-satisfying')`
|
||||
* `require('semver/ranges/min-satisfying')`
|
||||
* `require('semver/ranges/min-version')`
|
||||
* `require('semver/ranges/outside')`
|
||||
* `require('semver/ranges/to-comparators')`
|
||||
* `require('semver/ranges/valid')`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user