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