| 1 | semver(1) -- The semantic versioner for npm
|
|---|
| 2 | ===========================================
|
|---|
| 3 |
|
|---|
| 4 | ## Install
|
|---|
| 5 |
|
|---|
| 6 | ```bash
|
|---|
| 7 | npm install semver
|
|---|
| 8 | ````
|
|---|
| 9 |
|
|---|
| 10 | ## Usage
|
|---|
| 11 |
|
|---|
| 12 | As a node module:
|
|---|
| 13 |
|
|---|
| 14 | ```js
|
|---|
| 15 | const semver = require('semver')
|
|---|
| 16 |
|
|---|
| 17 | semver.valid('1.2.3') // '1.2.3'
|
|---|
| 18 | semver.valid('a.b.c') // null
|
|---|
| 19 | semver.clean(' =v1.2.3 ') // '1.2.3'
|
|---|
| 20 | semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
|
|---|
| 21 | semver.gt('1.2.3', '9.8.7') // false
|
|---|
| 22 | semver.lt('1.2.3', '9.8.7') // true
|
|---|
| 23 | semver.minVersion('>=1.0.0') // '1.0.0'
|
|---|
| 24 | semver.valid(semver.coerce('v2')) // '2.0.0'
|
|---|
| 25 | semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
|
|---|
| 26 | ```
|
|---|
| 27 |
|
|---|
| 28 | You can also just load the module for the function that you care about if
|
|---|
| 29 | you'd like to minimize your footprint.
|
|---|
| 30 |
|
|---|
| 31 | ```js
|
|---|
| 32 | // load the whole API at once in a single object
|
|---|
| 33 | const semver = require('semver')
|
|---|
| 34 |
|
|---|
| 35 | // or just load the bits you need
|
|---|
| 36 | // all of them listed here, just pick and choose what you want
|
|---|
| 37 |
|
|---|
| 38 | // classes
|
|---|
| 39 | const SemVer = require('semver/classes/semver')
|
|---|
| 40 | const Comparator = require('semver/classes/comparator')
|
|---|
| 41 | const Range = require('semver/classes/range')
|
|---|
| 42 |
|
|---|
| 43 | // functions for working with versions
|
|---|
| 44 | const semverParse = require('semver/functions/parse')
|
|---|
| 45 | const semverValid = require('semver/functions/valid')
|
|---|
| 46 | const semverClean = require('semver/functions/clean')
|
|---|
| 47 | const semverInc = require('semver/functions/inc')
|
|---|
| 48 | const semverDiff = require('semver/functions/diff')
|
|---|
| 49 | const semverMajor = require('semver/functions/major')
|
|---|
| 50 | const semverMinor = require('semver/functions/minor')
|
|---|
| 51 | const semverPatch = require('semver/functions/patch')
|
|---|
| 52 | const semverPrerelease = require('semver/functions/prerelease')
|
|---|
| 53 | const semverCompare = require('semver/functions/compare')
|
|---|
| 54 | const semverRcompare = require('semver/functions/rcompare')
|
|---|
| 55 | const semverCompareLoose = require('semver/functions/compare-loose')
|
|---|
| 56 | const semverCompareBuild = require('semver/functions/compare-build')
|
|---|
| 57 | const semverSort = require('semver/functions/sort')
|
|---|
| 58 | const semverRsort = require('semver/functions/rsort')
|
|---|
| 59 | const semverTruncate = require('semver/functions/truncate')
|
|---|
| 60 |
|
|---|
| 61 | // low-level comparators between versions
|
|---|
| 62 | const semverGt = require('semver/functions/gt')
|
|---|
| 63 | const semverLt = require('semver/functions/lt')
|
|---|
| 64 | const semverEq = require('semver/functions/eq')
|
|---|
| 65 | const semverNeq = require('semver/functions/neq')
|
|---|
| 66 | const semverGte = require('semver/functions/gte')
|
|---|
| 67 | const semverLte = require('semver/functions/lte')
|
|---|
| 68 | const semverCmp = require('semver/functions/cmp')
|
|---|
| 69 | const semverCoerce = require('semver/functions/coerce')
|
|---|
| 70 |
|
|---|
| 71 | // working with ranges
|
|---|
| 72 | const semverSatisfies = require('semver/functions/satisfies')
|
|---|
| 73 | const semverMaxSatisfying = require('semver/ranges/max-satisfying')
|
|---|
| 74 | const semverMinSatisfying = require('semver/ranges/min-satisfying')
|
|---|
| 75 | const semverToComparators = require('semver/ranges/to-comparators')
|
|---|
| 76 | const semverMinVersion = require('semver/ranges/min-version')
|
|---|
| 77 | const semverValidRange = require('semver/ranges/valid')
|
|---|
| 78 | const semverOutside = require('semver/ranges/outside')
|
|---|
| 79 | const semverGtr = require('semver/ranges/gtr')
|
|---|
| 80 | const semverLtr = require('semver/ranges/ltr')
|
|---|
| 81 | const semverIntersects = require('semver/ranges/intersects')
|
|---|
| 82 | const semverSimplifyRange = require('semver/ranges/simplify')
|
|---|
| 83 | const semverRangeSubset = require('semver/ranges/subset')
|
|---|
| 84 | ```
|
|---|
| 85 |
|
|---|
| 86 | As a command-line utility:
|
|---|
| 87 |
|
|---|
| 88 | ```
|
|---|
| 89 | $ semver -h
|
|---|
| 90 |
|
|---|
| 91 | A JavaScript implementation of the https://semver.org/ specification
|
|---|
| 92 | Copyright Isaac Z. Schlueter
|
|---|
| 93 |
|
|---|
| 94 | Usage: semver [options] <version> [<version> [...]]
|
|---|
| 95 | Prints valid versions sorted by SemVer precedence
|
|---|
| 96 |
|
|---|
| 97 | Options:
|
|---|
| 98 | -r --range <range>
|
|---|
| 99 | Print versions that match the specified range.
|
|---|
| 100 |
|
|---|
| 101 | -i --increment [<level>]
|
|---|
| 102 | Increment a version by the specified level. Level can
|
|---|
| 103 | be one of: major, minor, patch, premajor, preminor,
|
|---|
| 104 | prepatch, prerelease, or release. Default level is 'patch'.
|
|---|
| 105 | Only one version may be specified.
|
|---|
| 106 |
|
|---|
| 107 | --preid <identifier>
|
|---|
| 108 | Identifier to be used to prefix premajor, preminor,
|
|---|
| 109 | prepatch or prerelease version increments.
|
|---|
| 110 |
|
|---|
| 111 | -l --loose
|
|---|
| 112 | Interpret versions and ranges loosely
|
|---|
| 113 |
|
|---|
| 114 | -n <0|1|false>
|
|---|
| 115 | Base number for prerelease identifier (default: 0).
|
|---|
| 116 | Use false to omit the number altogether.
|
|---|
| 117 |
|
|---|
| 118 | -p --include-prerelease
|
|---|
| 119 | Always include prerelease versions in range matching
|
|---|
| 120 |
|
|---|
| 121 | -c --coerce
|
|---|
| 122 | Coerce a string into SemVer if possible
|
|---|
| 123 | (does not imply --loose)
|
|---|
| 124 |
|
|---|
| 125 | --rtl
|
|---|
| 126 | Coerce version strings right to left
|
|---|
| 127 |
|
|---|
| 128 | --ltr
|
|---|
| 129 | Coerce version strings left to right (default)
|
|---|
| 130 |
|
|---|
| 131 | Program exits successfully if any valid version satisfies
|
|---|
| 132 | all supplied ranges, and prints all satisfying versions.
|
|---|
| 133 |
|
|---|
| 134 | If no satisfying versions are found, then exits failure.
|
|---|
| 135 |
|
|---|
| 136 | Versions are printed in ascending order, so supplying
|
|---|
| 137 | multiple versions to the utility will just sort them.
|
|---|
| 138 | ```
|
|---|
| 139 |
|
|---|
| 140 | ## Versions
|
|---|
| 141 |
|
|---|
| 142 | A "version" is described by the `v2.0.0` specification found at
|
|---|
| 143 | <https://semver.org/>.
|
|---|
| 144 |
|
|---|
| 145 | A leading `"="` or `"v"` character is stripped off and ignored.
|
|---|
| 146 | Support for stripping a leading "v" is kept for compatibility with `v1.0.0` of the SemVer
|
|---|
| 147 | specification but should not be used anymore.
|
|---|
| 148 |
|
|---|
| 149 | ## Ranges
|
|---|
| 150 |
|
|---|
| 151 | A `version range` is a set of `comparators` that specify versions
|
|---|
| 152 | that satisfy the range.
|
|---|
| 153 |
|
|---|
| 154 | A `comparator` is composed of an `operator` and a `version`. The set
|
|---|
| 155 | of primitive `operators` is:
|
|---|
| 156 |
|
|---|
| 157 | * `<` Less than
|
|---|
| 158 | * `<=` Less than or equal to
|
|---|
| 159 | * `>` Greater than
|
|---|
| 160 | * `>=` Greater than or equal to
|
|---|
| 161 | * `=` Equal. If no operator is specified, then equality is assumed,
|
|---|
| 162 | so this operator is optional but MAY be included.
|
|---|
| 163 |
|
|---|
| 164 | For example, the comparator `>=1.2.7` would match the versions
|
|---|
| 165 | `1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
|
|---|
| 166 | or `1.1.0`. The comparator `>1` is equivalent to `>=2.0.0` and
|
|---|
| 167 | would match the versions `2.0.0` and `3.1.0`, but not the versions
|
|---|
| 168 | `1.0.1` or `1.1.0`.
|
|---|
| 169 |
|
|---|
| 170 | Comparators can be joined by whitespace to form a `comparator set`,
|
|---|
| 171 | which is satisfied by the **intersection** of all of the comparators
|
|---|
| 172 | it includes.
|
|---|
| 173 |
|
|---|
| 174 | A range is composed of one or more comparator sets, joined by `||`. A
|
|---|
| 175 | version matches a range if and only if every comparator in at least
|
|---|
| 176 | one of the `||`-separated comparator sets is satisfied by the version.
|
|---|
| 177 |
|
|---|
| 178 | For example, the range `>=1.2.7 <1.3.0` would match the versions
|
|---|
| 179 | `1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
|
|---|
| 180 | or `1.1.0`.
|
|---|
| 181 |
|
|---|
| 182 | The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
|
|---|
| 183 | `1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
|
|---|
| 184 |
|
|---|
| 185 | ### Prerelease Tags
|
|---|
| 186 |
|
|---|
| 187 | If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
|
|---|
| 188 | it will only be allowed to satisfy comparator sets if at least one
|
|---|
| 189 | comparator with the same `[major, minor, patch]` tuple also has a
|
|---|
| 190 | prerelease tag.
|
|---|
| 191 |
|
|---|
| 192 | For example, the range `>1.2.3-alpha.3` would be allowed to match the
|
|---|
| 193 | version `1.2.3-alpha.7`, but it would *not* be satisfied by
|
|---|
| 194 | `3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
|
|---|
| 195 | than" `1.2.3-alpha.3` according to the SemVer sort rules. The version
|
|---|
| 196 | range only accepts prerelease tags on the `1.2.3` version.
|
|---|
| 197 | Version `3.4.5` *would* satisfy the range because it does not have a
|
|---|
| 198 | prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
|
|---|
| 199 |
|
|---|
| 200 | The purpose of this behavior is twofold. First, prerelease versions
|
|---|
| 201 | frequently are updated very quickly, and contain many breaking changes
|
|---|
| 202 | that are (by the author's design) not yet fit for public consumption.
|
|---|
| 203 | Therefore, by default, they are excluded from range-matching
|
|---|
| 204 | semantics.
|
|---|
| 205 |
|
|---|
| 206 | Second, a user who has opted into using a prerelease version has
|
|---|
| 207 | indicated the intent to use *that specific* set of
|
|---|
| 208 | alpha/beta/rc versions. By including a prerelease tag in the range,
|
|---|
| 209 | the user is indicating that they are aware of the risk. However, it
|
|---|
| 210 | is still not appropriate to assume that they have opted into taking a
|
|---|
| 211 | similar risk on the *next* set of prerelease versions.
|
|---|
| 212 |
|
|---|
| 213 | Note that this behavior can be suppressed (treating all prerelease
|
|---|
| 214 | versions as if they were normal versions, for range-matching)
|
|---|
| 215 | by setting the `includePrerelease` flag on the options
|
|---|
| 216 | object to any
|
|---|
| 217 | [functions](https://github.com/npm/node-semver#functions) that do
|
|---|
| 218 | range matching.
|
|---|
| 219 |
|
|---|
| 220 | #### Prerelease Identifiers
|
|---|
| 221 |
|
|---|
| 222 | The method `.inc` takes an additional `identifier` string argument that
|
|---|
| 223 | will append the value of the string as a prerelease identifier:
|
|---|
| 224 |
|
|---|
| 225 | ```javascript
|
|---|
| 226 | semver.inc('1.2.3', 'prerelease', 'beta')
|
|---|
| 227 | // '1.2.4-beta.0'
|
|---|
| 228 | ```
|
|---|
| 229 |
|
|---|
| 230 | command-line example:
|
|---|
| 231 |
|
|---|
| 232 | ```bash
|
|---|
| 233 | $ semver 1.2.3 -i prerelease --preid beta
|
|---|
| 234 | 1.2.4-beta.0
|
|---|
| 235 | ```
|
|---|
| 236 |
|
|---|
| 237 | Which then can be used to increment further:
|
|---|
| 238 |
|
|---|
| 239 | ```bash
|
|---|
| 240 | $ semver 1.2.4-beta.0 -i prerelease
|
|---|
| 241 | 1.2.4-beta.1
|
|---|
| 242 | ```
|
|---|
| 243 |
|
|---|
| 244 | To get out of the prerelease phase, use the `release` option:
|
|---|
| 245 |
|
|---|
| 246 | ```bash
|
|---|
| 247 | $ semver 1.2.4-beta.1 -i release
|
|---|
| 248 | 1.2.4
|
|---|
| 249 | ```
|
|---|
| 250 |
|
|---|
| 251 | #### Prerelease Identifier Base
|
|---|
| 252 |
|
|---|
| 253 | The method `.inc` takes an optional parameter 'identifierBase' string
|
|---|
| 254 | that will let you let your prerelease number as zero-based or one-based.
|
|---|
| 255 | Set to `false` to omit the prerelease number altogether.
|
|---|
| 256 | If you do not specify this parameter, it will default to zero-based.
|
|---|
| 257 |
|
|---|
| 258 | ```javascript
|
|---|
| 259 | semver.inc('1.2.3', 'prerelease', 'beta', '1')
|
|---|
| 260 | // '1.2.4-beta.1'
|
|---|
| 261 | ```
|
|---|
| 262 |
|
|---|
| 263 | ```javascript
|
|---|
| 264 | semver.inc('1.2.3', 'prerelease', 'beta', false)
|
|---|
| 265 | // '1.2.4-beta'
|
|---|
| 266 | ```
|
|---|
| 267 |
|
|---|
| 268 | command-line example:
|
|---|
| 269 |
|
|---|
| 270 | ```bash
|
|---|
| 271 | $ semver 1.2.3 -i prerelease --preid beta -n 1
|
|---|
| 272 | 1.2.4-beta.1
|
|---|
| 273 | ```
|
|---|
| 274 |
|
|---|
| 275 | ```bash
|
|---|
| 276 | $ semver 1.2.3 -i prerelease --preid beta -n false
|
|---|
| 277 | 1.2.4-beta
|
|---|
| 278 | ```
|
|---|
| 279 |
|
|---|
| 280 | ### Advanced Range Syntax
|
|---|
| 281 |
|
|---|
| 282 | Advanced range syntax desugars to primitive comparators in
|
|---|
| 283 | deterministic ways.
|
|---|
| 284 |
|
|---|
| 285 | Advanced ranges may be combined in the same way as primitive
|
|---|
| 286 | comparators using white space or `||`.
|
|---|
| 287 |
|
|---|
| 288 | #### Hyphen Ranges `X.Y.Z - A.B.C`
|
|---|
| 289 |
|
|---|
| 290 | Specifies an inclusive set.
|
|---|
| 291 |
|
|---|
| 292 | * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
|
|---|
| 293 |
|
|---|
| 294 | If a partial version is provided as the first version in the inclusive
|
|---|
| 295 | range, then the missing pieces are replaced with zeroes.
|
|---|
| 296 |
|
|---|
| 297 | * `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
|
|---|
| 298 |
|
|---|
| 299 | If a partial version is provided as the second version in the
|
|---|
| 300 | inclusive range, then all versions that start with the supplied parts
|
|---|
| 301 | of the tuple are accepted, but nothing that would be greater than the
|
|---|
| 302 | provided tuple parts.
|
|---|
| 303 |
|
|---|
| 304 | * `1.2.3 - 2.3` := `>=1.2.3 <2.4.0-0`
|
|---|
| 305 | * `1.2.3 - 2` := `>=1.2.3 <3.0.0-0`
|
|---|
| 306 |
|
|---|
| 307 | #### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
|
|---|
| 308 |
|
|---|
| 309 | Any of `X`, `x`, or `*` may be used to "stand in" for one of the
|
|---|
| 310 | numeric values in the `[major, minor, patch]` tuple.
|
|---|
| 311 |
|
|---|
| 312 | * `*` := `>=0.0.0` (Any non-prerelease version satisfies, unless
|
|---|
| 313 | `includePrerelease` is specified, in which case any version at all
|
|---|
| 314 | satisfies)
|
|---|
| 315 | * `1.x` := `>=1.0.0 <2.0.0-0` (Matching major version)
|
|---|
| 316 | * `1.2.x` := `>=1.2.0 <1.3.0-0` (Matching major and minor versions)
|
|---|
| 317 |
|
|---|
| 318 | A partial version range is treated as an X-Range, so the special
|
|---|
| 319 | character is in fact optional.
|
|---|
| 320 |
|
|---|
| 321 | * `""` (empty string) := `*` := `>=0.0.0`
|
|---|
| 322 | * `1` := `1.x.x` := `>=1.0.0 <2.0.0-0`
|
|---|
| 323 | * `1.2` := `1.2.x` := `>=1.2.0 <1.3.0-0`
|
|---|
| 324 |
|
|---|
| 325 | #### Tilde Ranges `~1.2.3` `~1.2` `~1`
|
|---|
| 326 |
|
|---|
| 327 | Allows patch-level changes if a minor version is specified on the
|
|---|
| 328 | comparator. Allows minor-level changes if not.
|
|---|
| 329 |
|
|---|
| 330 | * `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0-0`
|
|---|
| 331 | * `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0-0` (Same as `1.2.x`)
|
|---|
| 332 | * `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0-0` (Same as `1.x`)
|
|---|
| 333 | * `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0-0`
|
|---|
| 334 | * `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0-0` (Same as `0.2.x`)
|
|---|
| 335 | * `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0-0` (Same as `0.x`)
|
|---|
| 336 | * `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0-0` Note that prereleases in
|
|---|
| 337 | the `1.2.3` version will be allowed, if they are greater than or
|
|---|
| 338 | equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
|
|---|
| 339 | `1.2.4-beta.2` would not, because it is a prerelease of a
|
|---|
| 340 | different `[major, minor, patch]` tuple.
|
|---|
| 341 |
|
|---|
| 342 | #### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
|
|---|
| 343 |
|
|---|
| 344 | Allows changes that do not modify the left-most non-zero element in the
|
|---|
| 345 | `[major, minor, patch]` tuple. In other words, this allows patch and
|
|---|
| 346 | minor updates for versions `1.0.0` and above, patch updates for
|
|---|
| 347 | versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
|
|---|
| 348 |
|
|---|
| 349 | Many authors treat a `0.x` version as if the `x` were the major
|
|---|
| 350 | "breaking-change" indicator.
|
|---|
| 351 |
|
|---|
| 352 | Caret ranges are ideal when an author may make breaking changes
|
|---|
| 353 | between `0.2.4` and `0.3.0` releases, which is a common practice.
|
|---|
| 354 | However, it presumes that there will *not* be breaking changes between
|
|---|
| 355 | `0.2.4` and `0.2.5`. It allows for changes that are presumed to be
|
|---|
| 356 | additive (but non-breaking), according to commonly observed practices.
|
|---|
| 357 |
|
|---|
| 358 | * `^1.2.3` := `>=1.2.3 <2.0.0-0`
|
|---|
| 359 | * `^0.2.3` := `>=0.2.3 <0.3.0-0`
|
|---|
| 360 | * `^0.0.3` := `>=0.0.3 <0.0.4-0`
|
|---|
| 361 | * `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0-0` Note that prereleases in
|
|---|
| 362 | the `1.2.3` version will be allowed, if they are greater than or
|
|---|
| 363 | equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but
|
|---|
| 364 | `1.2.4-beta.2` would not, because it is a prerelease of a
|
|---|
| 365 | different `[major, minor, patch]` tuple.
|
|---|
| 366 | * `^0.0.3-beta` := `>=0.0.3-beta <0.0.4-0` Note that prereleases in the
|
|---|
| 367 | `0.0.3` version *only* will be allowed, if they are greater than or
|
|---|
| 368 | equal to `beta`. So, `0.0.3-pr.2` would be allowed.
|
|---|
| 369 |
|
|---|
| 370 | When parsing caret ranges, a missing `patch` value desugars to the
|
|---|
| 371 | number `0`, but will allow flexibility within that value, even if the
|
|---|
| 372 | major and minor versions are both `0`.
|
|---|
| 373 |
|
|---|
| 374 | * `^1.2.x` := `>=1.2.0 <2.0.0-0`
|
|---|
| 375 | * `^0.0.x` := `>=0.0.0 <0.1.0-0`
|
|---|
| 376 | * `^0.0` := `>=0.0.0 <0.1.0-0`
|
|---|
| 377 |
|
|---|
| 378 | A missing `minor` and `patch` values will desugar to zero, but also
|
|---|
| 379 | allow flexibility within those values, even if the major version is
|
|---|
| 380 | zero.
|
|---|
| 381 |
|
|---|
| 382 | * `^1.x` := `>=1.0.0 <2.0.0-0`
|
|---|
| 383 | * `^0.x` := `>=0.0.0 <1.0.0-0`
|
|---|
| 384 |
|
|---|
| 385 | ### Range Grammar
|
|---|
| 386 |
|
|---|
| 387 | Putting all this together, here is a Backus-Naur grammar for ranges,
|
|---|
| 388 | for the benefit of parser authors:
|
|---|
| 389 |
|
|---|
| 390 | ```bnf
|
|---|
| 391 | range-set ::= range ( logical-or range ) *
|
|---|
| 392 | logical-or ::= ( ' ' ) * '||' ( ' ' ) *
|
|---|
| 393 | range ::= hyphen | simple ( ' ' simple ) * | ''
|
|---|
| 394 | hyphen ::= partial ' - ' partial
|
|---|
| 395 | simple ::= primitive | partial | tilde | caret
|
|---|
| 396 | primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
|
|---|
| 397 | partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
|
|---|
| 398 | xr ::= 'x' | 'X' | '*' | nr
|
|---|
| 399 | nr ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
|
|---|
| 400 | tilde ::= '~' partial
|
|---|
| 401 | caret ::= '^' partial
|
|---|
| 402 | qualifier ::= ( '-' pre )? ( '+' build )?
|
|---|
| 403 | pre ::= prepart ( '.' prepart ) *
|
|---|
| 404 | prepart ::= nr | alphanumid
|
|---|
| 405 | build ::= buildid ( '.' buildid ) *
|
|---|
| 406 | alphanumid ::= ( ['0'-'9'] ) * [-A-Za-z] [-0-9A-Za-z] *
|
|---|
| 407 | buildid ::= [-0-9A-Za-z]+
|
|---|
| 408 | ```
|
|---|
| 409 |
|
|---|
| 410 | Note: Prerelease identifiers (`pre`) use `nr` for numeric parts, which
|
|---|
| 411 | disallows leading zeros (e.g., `1.2.3-00` is invalid). Build metadata
|
|---|
| 412 | identifiers (`build`) allow any alphanumeric string including leading
|
|---|
| 413 | zeros (e.g., `1.2.3+00` is valid). This matches the
|
|---|
| 414 | [SemVer 2.0.0 specification](https://semver.org/#spec-item-9).
|
|---|
| 415 |
|
|---|
| 416 | ## Functions
|
|---|
| 417 |
|
|---|
| 418 | All methods and classes take a final `options` object argument. All
|
|---|
| 419 | options in this object are `false` by default. The options supported
|
|---|
| 420 | are:
|
|---|
| 421 |
|
|---|
| 422 | - `loose`: Be more forgiving about not-quite-valid semver strings.
|
|---|
| 423 | (Any resulting output will always be 100% strict compliant, of
|
|---|
| 424 | course.) For backwards compatibility reasons, if the `options`
|
|---|
| 425 | argument is a boolean value instead of an object, it is interpreted
|
|---|
| 426 | to be the `loose` param.
|
|---|
| 427 | - `includePrerelease`: Set to suppress the [default
|
|---|
| 428 | behavior](https://github.com/npm/node-semver#prerelease-tags) of
|
|---|
| 429 | excluding prerelease tagged versions from ranges unless they are
|
|---|
| 430 | explicitly opted into.
|
|---|
| 431 |
|
|---|
| 432 | Strict-mode Comparators and Ranges will be strict about the SemVer
|
|---|
| 433 | strings that they parse.
|
|---|
| 434 |
|
|---|
| 435 | * `valid(v)`: Return the parsed version, or null if it's not valid.
|
|---|
| 436 | * `inc(v, releaseType, options, identifier, identifierBase)`:
|
|---|
| 437 | Return the version incremented by the release
|
|---|
| 438 | type (`major`, `premajor`, `minor`, `preminor`, `patch`,
|
|---|
| 439 | `prepatch`, `prerelease`, or `release`), or null if it's not valid
|
|---|
| 440 | * `premajor` in one call will bump the version up to the next major
|
|---|
| 441 | version and down to a prerelease of that major version.
|
|---|
| 442 | `preminor`, and `prepatch` work the same way.
|
|---|
| 443 | * If called from a non-prerelease version, `prerelease` will work the
|
|---|
| 444 | same as `prepatch`. It increments the patch version and then makes a
|
|---|
| 445 | prerelease. If the input version is already a prerelease it simply
|
|---|
| 446 | increments it.
|
|---|
| 447 | * `release` will remove any prerelease part of the version.
|
|---|
| 448 | * `identifier` can be used to prefix `premajor`, `preminor`,
|
|---|
| 449 | `prepatch`, or `prerelease` version increments. `identifierBase`
|
|---|
| 450 | is the base to be used for the `prerelease` identifier.
|
|---|
| 451 | * `prerelease(v)`: Returns an array of prerelease components, or null
|
|---|
| 452 | if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
|
|---|
| 453 | * `major(v)`: Return the major version number.
|
|---|
| 454 | * `minor(v)`: Return the minor version number.
|
|---|
| 455 | * `patch(v)`: Return the patch version number.
|
|---|
| 456 | * `intersects(r1, r2, loose)`: Return true if the two supplied ranges
|
|---|
| 457 | or comparators intersect.
|
|---|
| 458 | * `parse(v)`: Attempt to parse a string as a semantic version, returning either
|
|---|
| 459 | a `SemVer` object or `null`.
|
|---|
| 460 | * `truncate(v, releaseType)`: Return the version with components _lower_
|
|---|
| 461 | than `releaseType` dropped off, e.g.:
|
|---|
| 462 | * `major` removes build & prerelease info and sets minor & patch to 0.
|
|---|
| 463 | * `minor` removes build & prerelease info, and sets patch to 0
|
|---|
| 464 | * `patch` removes build & prerelease info
|
|---|
| 465 | * All prerelease types remove build info only
|
|---|
| 466 |
|
|---|
| 467 | ### Comparison
|
|---|
| 468 |
|
|---|
| 469 | * `gt(v1, v2)`: `v1 > v2`
|
|---|
| 470 | * `gte(v1, v2)`: `v1 >= v2`
|
|---|
| 471 | * `lt(v1, v2)`: `v1 < v2`
|
|---|
| 472 | * `lte(v1, v2)`: `v1 <= v2`
|
|---|
| 473 | * `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent,
|
|---|
| 474 | even if they're not the same string. You already know how to
|
|---|
| 475 | compare strings.
|
|---|
| 476 | * `neq(v1, v2)`: `v1 != v2` The opposite of `eq`.
|
|---|
| 477 | * `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call
|
|---|
| 478 | the corresponding function above. `"==="` and `"!=="` do simple
|
|---|
| 479 | string comparison, but are included for completeness. Throws if an
|
|---|
| 480 | invalid comparison string is provided.
|
|---|
| 481 | * `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if
|
|---|
| 482 | `v2` is greater. Sorts in ascending order if passed to `Array.sort()`.
|
|---|
| 483 | * `rcompare(v1, v2)`: The reverse of `compare`. Sorts an array of versions
|
|---|
| 484 | in descending order when passed to `Array.sort()`.
|
|---|
| 485 | * `compareBuild(v1, v2)`: The same as `compare` but considers `build` when two versions
|
|---|
| 486 | are equal. Sorts in ascending order if passed to `Array.sort()`.
|
|---|
| 487 | * `compareLoose(v1, v2)`: Short for `compare(v1, v2, { loose: true })`.
|
|---|
| 488 | * `diff(v1, v2)`: Returns the difference between two versions by the release type
|
|---|
| 489 | (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
|
|---|
| 490 | or null if the versions are the same.
|
|---|
| 491 |
|
|---|
| 492 | ### Sorting
|
|---|
| 493 |
|
|---|
| 494 | * `sort(versions)`: Returns a sorted array of versions based on the `compareBuild`
|
|---|
| 495 | function.
|
|---|
| 496 | * `rsort(versions)`: The reverse of `sort`. Returns an array of versions based on
|
|---|
| 497 | the `compareBuild` function in descending order.
|
|---|
| 498 |
|
|---|
| 499 | ### Comparators
|
|---|
| 500 |
|
|---|
| 501 | * `intersects(comparator)`: Return true if the comparators intersect
|
|---|
| 502 |
|
|---|
| 503 | ### Ranges
|
|---|
| 504 |
|
|---|
| 505 | * `validRange(range)`: Return the valid range or null if it's not valid.
|
|---|
| 506 | * `satisfies(version, range)`: Return true if the version satisfies the
|
|---|
| 507 | range.
|
|---|
| 508 | * `maxSatisfying(versions, range)`: Return the highest version in the list
|
|---|
| 509 | that satisfies the range, or `null` if none of them do.
|
|---|
| 510 | * `minSatisfying(versions, range)`: Return the lowest version in the list
|
|---|
| 511 | that satisfies the range, or `null` if none of them do.
|
|---|
| 512 | * `minVersion(range)`: Return the lowest version that can match
|
|---|
| 513 | the given range.
|
|---|
| 514 | * `gtr(version, range)`: Return `true` if the version is greater than all the
|
|---|
| 515 | versions possible in the range.
|
|---|
| 516 | * `ltr(version, range)`: Return `true` if the version is less than all the
|
|---|
| 517 | versions possible in the range.
|
|---|
| 518 | * `outside(version, range, hilo)`: Return true if the version is outside
|
|---|
| 519 | the bounds of the range in either the high or low direction. The
|
|---|
| 520 | `hilo` argument must be either the string `'>'` or `'<'`. (This is
|
|---|
| 521 | the function called by `gtr` and `ltr`.)
|
|---|
| 522 | * `intersects(range)`: Return true if any of the range comparators intersect.
|
|---|
| 523 | * `simplifyRange(versions, range)`: Return a "simplified" range that
|
|---|
| 524 | matches the same items in the `versions` list as the range specified. Note
|
|---|
| 525 | that it does *not* guarantee that it would match the same versions in all
|
|---|
| 526 | cases, only for the set of versions provided. This is useful when
|
|---|
| 527 | generating ranges by joining together multiple versions with `||`
|
|---|
| 528 | programmatically, to provide the user with something a bit more
|
|---|
| 529 | ergonomic. If the provided range is shorter in string-length than the
|
|---|
| 530 | generated range, then that is returned.
|
|---|
| 531 | * `subset(subRange, superRange)`: Return `true` if the `subRange` range is
|
|---|
| 532 | entirely contained by the `superRange` range.
|
|---|
| 533 |
|
|---|
| 534 | Note that, since ranges may be non-contiguous, a version might not be
|
|---|
| 535 | greater than a range, less than a range, *or* satisfy a range! For
|
|---|
| 536 | example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9`
|
|---|
| 537 | until `2.0.0`, so version `1.2.10` would not be greater than the
|
|---|
| 538 | range (because `2.0.1` satisfies, which is higher), nor less than the
|
|---|
| 539 | range (since `1.2.8` satisfies, which is lower), and it also does not
|
|---|
| 540 | satisfy the range.
|
|---|
| 541 |
|
|---|
| 542 | If you want to know if a version satisfies or does not satisfy a
|
|---|
| 543 | range, use the `satisfies(version, range)` function.
|
|---|
| 544 |
|
|---|
| 545 | ### Coercion
|
|---|
| 546 |
|
|---|
| 547 | * `coerce(version, options)`: Coerces a string to semver if possible
|
|---|
| 548 |
|
|---|
| 549 | This aims to provide a very forgiving translation of a non-semver string to
|
|---|
| 550 | semver. It looks for the first digit in a string and consumes all
|
|---|
| 551 | remaining characters which satisfy at least a partial semver (e.g., `1`,
|
|---|
| 552 | `1.2`, `1.2.3`) up to the max permitted length (256 characters). Longer
|
|---|
| 553 | versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`). All
|
|---|
| 554 | surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes
|
|---|
| 555 | `3.4.0`). Only text which lacks digits will fail coercion (`version one`
|
|---|
| 556 | is not valid). The maximum length for any semver component considered for
|
|---|
| 557 | coercion is 16 characters; longer components will be ignored
|
|---|
| 558 | (`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any
|
|---|
| 559 | semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value
|
|---|
| 560 | components are invalid (`9999999999999999.4.7.4` is likely invalid).
|
|---|
| 561 |
|
|---|
| 562 | If the `options.rtl` flag is set, then `coerce` will return the right-most
|
|---|
| 563 | coercible tuple that does not share an ending index with a longer coercible
|
|---|
| 564 | tuple. For example, `1.2.3.4` will return `2.3.4` in rtl mode, not
|
|---|
| 565 | `4.0.0`. `1.2.3/4` will return `4.0.0`, because the `4` is not a part of
|
|---|
| 566 | any other overlapping SemVer tuple.
|
|---|
| 567 |
|
|---|
| 568 | If the `options.includePrerelease` flag is set, then the `coerce` result will contain
|
|---|
| 569 | prerelease and build parts of a version. For example, `1.2.3.4-rc.1+rev.2`
|
|---|
| 570 | will preserve prerelease `rc.1` and build `rev.2` in the result.
|
|---|
| 571 |
|
|---|
| 572 | ### Clean
|
|---|
| 573 |
|
|---|
| 574 | * `clean(version)`: Clean a string to be a valid semver if possible
|
|---|
| 575 |
|
|---|
| 576 | This will return a cleaned and trimmed semver version. If the provided
|
|---|
| 577 | version is not valid a null will be returned. This does not work for
|
|---|
| 578 | ranges.
|
|---|
| 579 |
|
|---|
| 580 | ex.
|
|---|
| 581 | * `s.clean(' = v 2.1.5foo')`: `null`
|
|---|
| 582 | * `s.clean(' = v 2.1.5foo', { loose: true })`: `'2.1.5-foo'`
|
|---|
| 583 | * `s.clean(' = v 2.1.5-foo')`: `null`
|
|---|
| 584 | * `s.clean(' = v 2.1.5-foo', { loose: true })`: `'2.1.5-foo'`
|
|---|
| 585 | * `s.clean('=v2.1.5')`: `'2.1.5'`
|
|---|
| 586 | * `s.clean(' =v2.1.5')`: `'2.1.5'`
|
|---|
| 587 | * `s.clean(' 2.1.5 ')`: `'2.1.5'`
|
|---|
| 588 | * `s.clean('~1.0.0')`: `null`
|
|---|
| 589 |
|
|---|
| 590 | ## Constants
|
|---|
| 591 |
|
|---|
| 592 | As a convenience, helper constants are exported to provide information about what `node-semver` supports:
|
|---|
| 593 |
|
|---|
| 594 | ### `RELEASE_TYPES`
|
|---|
| 595 |
|
|---|
| 596 | - major
|
|---|
| 597 | - premajor
|
|---|
| 598 | - minor
|
|---|
| 599 | - preminor
|
|---|
| 600 | - patch
|
|---|
| 601 | - prepatch
|
|---|
| 602 | - prerelease
|
|---|
| 603 |
|
|---|
| 604 | ```
|
|---|
| 605 | const semver = require('semver');
|
|---|
| 606 |
|
|---|
| 607 | if (semver.RELEASE_TYPES.includes(arbitraryUserInput)) {
|
|---|
| 608 | console.log('This is a valid release type!');
|
|---|
| 609 | } else {
|
|---|
| 610 | console.warn('This is NOT a valid release type!');
|
|---|
| 611 | }
|
|---|
| 612 | ```
|
|---|
| 613 |
|
|---|
| 614 | ### `SEMVER_SPEC_VERSION`
|
|---|
| 615 |
|
|---|
| 616 | 2.0.0
|
|---|
| 617 |
|
|---|
| 618 | ```
|
|---|
| 619 | const semver = require('semver');
|
|---|
| 620 |
|
|---|
| 621 | console.log('We are currently using the semver specification version:', semver.SEMVER_SPEC_VERSION);
|
|---|
| 622 | ```
|
|---|
| 623 |
|
|---|
| 624 | ## Exported Modules
|
|---|
| 625 |
|
|---|
| 626 | <!--
|
|---|
| 627 | TODO: Make sure that all of these items are documented (classes aren't,
|
|---|
| 628 | eg), and then pull the module name into the documentation for that specific
|
|---|
| 629 | thing.
|
|---|
| 630 | -->
|
|---|
| 631 |
|
|---|
| 632 | You may pull in just the part of this semver utility that you need if you
|
|---|
| 633 | are sensitive to packing and tree-shaking concerns. The main
|
|---|
| 634 | `require('semver')` export uses getter functions to lazily load the parts
|
|---|
| 635 | of the API that are used.
|
|---|
| 636 |
|
|---|
| 637 | The following modules are available:
|
|---|
| 638 |
|
|---|
| 639 | * `require('semver')`
|
|---|
| 640 | * `require('semver/classes')`
|
|---|
| 641 | * `require('semver/classes/comparator')`
|
|---|
| 642 | * `require('semver/classes/range')`
|
|---|
| 643 | * `require('semver/classes/semver')`
|
|---|
| 644 | * `require('semver/functions/clean')`
|
|---|
| 645 | * `require('semver/functions/cmp')`
|
|---|
| 646 | * `require('semver/functions/coerce')`
|
|---|
| 647 | * `require('semver/functions/compare')`
|
|---|
| 648 | * `require('semver/functions/compare-build')`
|
|---|
| 649 | * `require('semver/functions/compare-loose')`
|
|---|
| 650 | * `require('semver/functions/diff')`
|
|---|
| 651 | * `require('semver/functions/eq')`
|
|---|
| 652 | * `require('semver/functions/gt')`
|
|---|
| 653 | * `require('semver/functions/gte')`
|
|---|
| 654 | * `require('semver/functions/inc')`
|
|---|
| 655 | * `require('semver/functions/lt')`
|
|---|
| 656 | * `require('semver/functions/lte')`
|
|---|
| 657 | * `require('semver/functions/major')`
|
|---|
| 658 | * `require('semver/functions/minor')`
|
|---|
| 659 | * `require('semver/functions/neq')`
|
|---|
| 660 | * `require('semver/functions/parse')`
|
|---|
| 661 | * `require('semver/functions/patch')`
|
|---|
| 662 | * `require('semver/functions/prerelease')`
|
|---|
| 663 | * `require('semver/functions/rcompare')`
|
|---|
| 664 | * `require('semver/functions/rsort')`
|
|---|
| 665 | * `require('semver/functions/satisfies')`
|
|---|
| 666 | * `require('semver/functions/sort')`
|
|---|
| 667 | * `require('semver/functions/truncate')`
|
|---|
| 668 | * `require('semver/functions/valid')`
|
|---|
| 669 | * `require('semver/ranges/gtr')`
|
|---|
| 670 | * `require('semver/ranges/intersects')`
|
|---|
| 671 | * `require('semver/ranges/ltr')`
|
|---|
| 672 | * `require('semver/ranges/max-satisfying')`
|
|---|
| 673 | * `require('semver/ranges/min-satisfying')`
|
|---|
| 674 | * `require('semver/ranges/min-version')`
|
|---|
| 675 | * `require('semver/ranges/outside')`
|
|---|
| 676 | * `require('semver/ranges/simplify')`
|
|---|
| 677 | * `require('semver/ranges/subset')`
|
|---|
| 678 | * `require('semver/ranges/to-comparators')`
|
|---|
| 679 | * `require('semver/ranges/valid')`
|
|---|
| 680 |
|
|---|