/ cloudformation-templates / node_modules / normalize-package-data / node_modules / semver / README.md
README.md
1 semver(1) -- The semantic versioner for npm 2 =========================================== 3 4 ## Install 5 6 ```bash 7 npm install --save 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 As a command-line utility: 29 30 ``` 31 $ semver -h 32 33 A JavaScript implementation of the https://semver.org/ specification 34 Copyright Isaac Z. Schlueter 35 36 Usage: semver [options] <version> [<version> [...]] 37 Prints valid versions sorted by SemVer precedence 38 39 Options: 40 -r --range <range> 41 Print versions that match the specified range. 42 43 -i --increment [<level>] 44 Increment a version by the specified level. Level can 45 be one of: major, minor, patch, premajor, preminor, 46 prepatch, or prerelease. Default level is 'patch'. 47 Only one version may be specified. 48 49 --preid <identifier> 50 Identifier to be used to prefix premajor, preminor, 51 prepatch or prerelease version increments. 52 53 -l --loose 54 Interpret versions and ranges loosely 55 56 -p --include-prerelease 57 Always include prerelease versions in range matching 58 59 -c --coerce 60 Coerce a string into SemVer if possible 61 (does not imply --loose) 62 63 Program exits successfully if any valid version satisfies 64 all supplied ranges, and prints all satisfying versions. 65 66 If no satisfying versions are found, then exits failure. 67 68 Versions are printed in ascending order, so supplying 69 multiple versions to the utility will just sort them. 70 ``` 71 72 ## Versions 73 74 A "version" is described by the `v2.0.0` specification found at 75 <https://semver.org/>. 76 77 A leading `"="` or `"v"` character is stripped off and ignored. 78 79 ## Ranges 80 81 A `version range` is a set of `comparators` which specify versions 82 that satisfy the range. 83 84 A `comparator` is composed of an `operator` and a `version`. The set 85 of primitive `operators` is: 86 87 * `<` Less than 88 * `<=` Less than or equal to 89 * `>` Greater than 90 * `>=` Greater than or equal to 91 * `=` Equal. If no operator is specified, then equality is assumed, 92 so this operator is optional, but MAY be included. 93 94 For example, the comparator `>=1.2.7` would match the versions 95 `1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6` 96 or `1.1.0`. 97 98 Comparators can be joined by whitespace to form a `comparator set`, 99 which is satisfied by the **intersection** of all of the comparators 100 it includes. 101 102 A range is composed of one or more comparator sets, joined by `||`. A 103 version matches a range if and only if every comparator in at least 104 one of the `||`-separated comparator sets is satisfied by the version. 105 106 For example, the range `>=1.2.7 <1.3.0` would match the versions 107 `1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`, 108 or `1.1.0`. 109 110 The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`, 111 `1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`. 112 113 ### Prerelease Tags 114 115 If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then 116 it will only be allowed to satisfy comparator sets if at least one 117 comparator with the same `[major, minor, patch]` tuple also has a 118 prerelease tag. 119 120 For example, the range `>1.2.3-alpha.3` would be allowed to match the 121 version `1.2.3-alpha.7`, but it would *not* be satisfied by 122 `3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater 123 than" `1.2.3-alpha.3` according to the SemVer sort rules. The version 124 range only accepts prerelease tags on the `1.2.3` version. The 125 version `3.4.5` *would* satisfy the range, because it does not have a 126 prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`. 127 128 The purpose for this behavior is twofold. First, prerelease versions 129 frequently are updated very quickly, and contain many breaking changes 130 that are (by the author's design) not yet fit for public consumption. 131 Therefore, by default, they are excluded from range matching 132 semantics. 133 134 Second, a user who has opted into using a prerelease version has 135 clearly indicated the intent to use *that specific* set of 136 alpha/beta/rc versions. By including a prerelease tag in the range, 137 the user is indicating that they are aware of the risk. However, it 138 is still not appropriate to assume that they have opted into taking a 139 similar risk on the *next* set of prerelease versions. 140 141 Note that this behavior can be suppressed (treating all prerelease 142 versions as if they were normal versions, for the purpose of range 143 matching) by setting the `includePrerelease` flag on the options 144 object to any 145 [functions](https://github.com/npm/node-semver#functions) that do 146 range matching. 147 148 #### Prerelease Identifiers 149 150 The method `.inc` takes an additional `identifier` string argument that 151 will append the value of the string as a prerelease identifier: 152 153 ```javascript 154 semver.inc('1.2.3', 'prerelease', 'beta') 155 // '1.2.4-beta.0' 156 ``` 157 158 command-line example: 159 160 ```bash 161 $ semver 1.2.3 -i prerelease --preid beta 162 1.2.4-beta.0 163 ``` 164 165 Which then can be used to increment further: 166 167 ```bash 168 $ semver 1.2.4-beta.0 -i prerelease 169 1.2.4-beta.1 170 ``` 171 172 ### Advanced Range Syntax 173 174 Advanced range syntax desugars to primitive comparators in 175 deterministic ways. 176 177 Advanced ranges may be combined in the same way as primitive 178 comparators using white space or `||`. 179 180 #### Hyphen Ranges `X.Y.Z - A.B.C` 181 182 Specifies an inclusive set. 183 184 * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` 185 186 If a partial version is provided as the first version in the inclusive 187 range, then the missing pieces are replaced with zeroes. 188 189 * `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4` 190 191 If a partial version is provided as the second version in the 192 inclusive range, then all versions that start with the supplied parts 193 of the tuple are accepted, but nothing that would be greater than the 194 provided tuple parts. 195 196 * `1.2.3 - 2.3` := `>=1.2.3 <2.4.0` 197 * `1.2.3 - 2` := `>=1.2.3 <3.0.0` 198 199 #### X-Ranges `1.2.x` `1.X` `1.2.*` `*` 200 201 Any of `X`, `x`, or `*` may be used to "stand in" for one of the 202 numeric values in the `[major, minor, patch]` tuple. 203 204 * `*` := `>=0.0.0` (Any version satisfies) 205 * `1.x` := `>=1.0.0 <2.0.0` (Matching major version) 206 * `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions) 207 208 A partial version range is treated as an X-Range, so the special 209 character is in fact optional. 210 211 * `""` (empty string) := `*` := `>=0.0.0` 212 * `1` := `1.x.x` := `>=1.0.0 <2.0.0` 213 * `1.2` := `1.2.x` := `>=1.2.0 <1.3.0` 214 215 #### Tilde Ranges `~1.2.3` `~1.2` `~1` 216 217 Allows patch-level changes if a minor version is specified on the 218 comparator. Allows minor-level changes if not. 219 220 * `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0` 221 * `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`) 222 * `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`) 223 * `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0` 224 * `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`) 225 * `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`) 226 * `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in 227 the `1.2.3` version will be allowed, if they are greater than or 228 equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but 229 `1.2.4-beta.2` would not, because it is a prerelease of a 230 different `[major, minor, patch]` tuple. 231 232 #### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4` 233 234 Allows changes that do not modify the left-most non-zero digit in the 235 `[major, minor, patch]` tuple. In other words, this allows patch and 236 minor updates for versions `1.0.0` and above, patch updates for 237 versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`. 238 239 Many authors treat a `0.x` version as if the `x` were the major 240 "breaking-change" indicator. 241 242 Caret ranges are ideal when an author may make breaking changes 243 between `0.2.4` and `0.3.0` releases, which is a common practice. 244 However, it presumes that there will *not* be breaking changes between 245 `0.2.4` and `0.2.5`. It allows for changes that are presumed to be 246 additive (but non-breaking), according to commonly observed practices. 247 248 * `^1.2.3` := `>=1.2.3 <2.0.0` 249 * `^0.2.3` := `>=0.2.3 <0.3.0` 250 * `^0.0.3` := `>=0.0.3 <0.0.4` 251 * `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in 252 the `1.2.3` version will be allowed, if they are greater than or 253 equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but 254 `1.2.4-beta.2` would not, because it is a prerelease of a 255 different `[major, minor, patch]` tuple. 256 * `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the 257 `0.0.3` version *only* will be allowed, if they are greater than or 258 equal to `beta`. So, `0.0.3-pr.2` would be allowed. 259 260 When parsing caret ranges, a missing `patch` value desugars to the 261 number `0`, but will allow flexibility within that value, even if the 262 major and minor versions are both `0`. 263 264 * `^1.2.x` := `>=1.2.0 <2.0.0` 265 * `^0.0.x` := `>=0.0.0 <0.1.0` 266 * `^0.0` := `>=0.0.0 <0.1.0` 267 268 A missing `minor` and `patch` values will desugar to zero, but also 269 allow flexibility within those values, even if the major version is 270 zero. 271 272 * `^1.x` := `>=1.0.0 <2.0.0` 273 * `^0.x` := `>=0.0.0 <1.0.0` 274 275 ### Range Grammar 276 277 Putting all this together, here is a Backus-Naur grammar for ranges, 278 for the benefit of parser authors: 279 280 ```bnf 281 range-set ::= range ( logical-or range ) * 282 logical-or ::= ( ' ' ) * '||' ( ' ' ) * 283 range ::= hyphen | simple ( ' ' simple ) * | '' 284 hyphen ::= partial ' - ' partial 285 simple ::= primitive | partial | tilde | caret 286 primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial 287 partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )? 288 xr ::= 'x' | 'X' | '*' | nr 289 nr ::= '0' | ['1'-'9'] ( ['0'-'9'] ) * 290 tilde ::= '~' partial 291 caret ::= '^' partial 292 qualifier ::= ( '-' pre )? ( '+' build )? 293 pre ::= parts 294 build ::= parts 295 parts ::= part ( '.' part ) * 296 part ::= nr | [-0-9A-Za-z]+ 297 ``` 298 299 ## Functions 300 301 All methods and classes take a final `options` object argument. All 302 options in this object are `false` by default. The options supported 303 are: 304 305 - `loose` Be more forgiving about not-quite-valid semver strings. 306 (Any resulting output will always be 100% strict compliant, of 307 course.) For backwards compatibility reasons, if the `options` 308 argument is a boolean value instead of an object, it is interpreted 309 to be the `loose` param. 310 - `includePrerelease` Set to suppress the [default 311 behavior](https://github.com/npm/node-semver#prerelease-tags) of 312 excluding prerelease tagged versions from ranges unless they are 313 explicitly opted into. 314 315 Strict-mode Comparators and Ranges will be strict about the SemVer 316 strings that they parse. 317 318 * `valid(v)`: Return the parsed version, or null if it's not valid. 319 * `inc(v, release)`: Return the version incremented by the release 320 type (`major`, `premajor`, `minor`, `preminor`, `patch`, 321 `prepatch`, or `prerelease`), or null if it's not valid 322 * `premajor` in one call will bump the version up to the next major 323 version and down to a prerelease of that major version. 324 `preminor`, and `prepatch` work the same way. 325 * If called from a non-prerelease version, the `prerelease` will work the 326 same as `prepatch`. It increments the patch version, then makes a 327 prerelease. If the input version is already a prerelease it simply 328 increments it. 329 * `prerelease(v)`: Returns an array of prerelease components, or null 330 if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]` 331 * `major(v)`: Return the major version number. 332 * `minor(v)`: Return the minor version number. 333 * `patch(v)`: Return the patch version number. 334 * `intersects(r1, r2, loose)`: Return true if the two supplied ranges 335 or comparators intersect. 336 * `parse(v)`: Attempt to parse a string as a semantic version, returning either 337 a `SemVer` object or `null`. 338 339 ### Comparison 340 341 * `gt(v1, v2)`: `v1 > v2` 342 * `gte(v1, v2)`: `v1 >= v2` 343 * `lt(v1, v2)`: `v1 < v2` 344 * `lte(v1, v2)`: `v1 <= v2` 345 * `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent, 346 even if they're not the exact same string. You already know how to 347 compare strings. 348 * `neq(v1, v2)`: `v1 != v2` The opposite of `eq`. 349 * `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call 350 the corresponding function above. `"==="` and `"!=="` do simple 351 string comparison, but are included for completeness. Throws if an 352 invalid comparison string is provided. 353 * `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if 354 `v2` is greater. Sorts in ascending order if passed to `Array.sort()`. 355 * `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions 356 in descending order when passed to `Array.sort()`. 357 * `diff(v1, v2)`: Returns difference between two versions by the release type 358 (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`), 359 or null if the versions are the same. 360 361 ### Comparators 362 363 * `intersects(comparator)`: Return true if the comparators intersect 364 365 ### Ranges 366 367 * `validRange(range)`: Return the valid range or null if it's not valid 368 * `satisfies(version, range)`: Return true if the version satisfies the 369 range. 370 * `maxSatisfying(versions, range)`: Return the highest version in the list 371 that satisfies the range, or `null` if none of them do. 372 * `minSatisfying(versions, range)`: Return the lowest version in the list 373 that satisfies the range, or `null` if none of them do. 374 * `minVersion(range)`: Return the lowest version that can possibly match 375 the given range. 376 * `gtr(version, range)`: Return `true` if version is greater than all the 377 versions possible in the range. 378 * `ltr(version, range)`: Return `true` if version is less than all the 379 versions possible in the range. 380 * `outside(version, range, hilo)`: Return true if the version is outside 381 the bounds of the range in either the high or low direction. The 382 `hilo` argument must be either the string `'>'` or `'<'`. (This is 383 the function called by `gtr` and `ltr`.) 384 * `intersects(range)`: Return true if any of the ranges comparators intersect 385 386 Note that, since ranges may be non-contiguous, a version might not be 387 greater than a range, less than a range, *or* satisfy a range! For 388 example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9` 389 until `2.0.0`, so the version `1.2.10` would not be greater than the 390 range (because `2.0.1` satisfies, which is higher), nor less than the 391 range (since `1.2.8` satisfies, which is lower), and it also does not 392 satisfy the range. 393 394 If you want to know if a version satisfies or does not satisfy a 395 range, use the `satisfies(version, range)` function. 396 397 ### Coercion 398 399 * `coerce(version)`: Coerces a string to semver if possible 400 401 This aims to provide a very forgiving translation of a non-semver string to 402 semver. It looks for the first digit in a string, and consumes all 403 remaining characters which satisfy at least a partial semver (e.g., `1`, 404 `1.2`, `1.2.3`) up to the max permitted length (256 characters). Longer 405 versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`). All 406 surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes 407 `3.4.0`). Only text which lacks digits will fail coercion (`version one` 408 is not valid). The maximum length for any semver component considered for 409 coercion is 16 characters; longer components will be ignored 410 (`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any 411 semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value 412 components are invalid (`9999999999999999.4.7.4` is likely invalid).