semver 5.4.1 → 5.7.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# changes log
+
+## 5.7
+
+* Add `minVersion` method
+
+## 5.6
+
+* Move boolean `loose` param to an options object, with
+  backwards-compatibility protection.
+* Add ability to opt out of special prerelease version handling with
+  the `includePrerelease` option flag.
+
+## 5.5
+
+* Add version coercion capabilities
+
+## 5.4
+
+* Add intersection checking
+
+## 5.3
+
+* Add `minSatisfying` method
+
+## 5.2
+
+* Add `prerelease(v)` that returns prerelease components
+
+## 5.1
+
+* Add Backus-Naur for ranges
+* Remove excessively cute inspection methods
+
+## 5.0
+
+* Remove AMD/Browserified build artifacts
+* Fix ltr and gtr when using the `*` range
+* Fix for range `*` with a prerelease identifier

package/README.md

@@ -20,6 +20,9 @@ semver.clean('  =v1.2.3   ') // '1.2.3'
 semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
 semver.gt('1.2.3', '9.8.7') // false
 semver.lt('1.2.3', '9.8.7') // true
+semver.minVersion('>=1.0.0') // '1.0.0'
+semver.valid(semver.coerce('v2')) // '2.0.0'
+semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
 ```
 
 As a command-line utility:
@@ -27,9 +30,7 @@ As a command-line utility:
 ```
 $ semver -h
 
-SemVer 5.3.0
-
-A JavaScript implementation of the http://semver.org/ specification
+A JavaScript implementation of the https://semver.org/ specification
 Copyright Isaac Z. Schlueter
 
 Usage: semver [options] <version> [<version> [...]]
@@ -52,6 +53,13 @@ Options:
 -l --loose
         Interpret versions and ranges loosely
 
+-p --include-prerelease
+        Always include prerelease versions in range matching
+
+-c --coerce
+        Coerce a string into SemVer if possible
+        (does not imply --loose)
+
 Program exits successfully if any valid version satisfies
 all supplied ranges, and prints all satisfying versions.
 
@@ -64,7 +72,7 @@ multiple versions to the utility will just sort them.
 ## Versions
 
 A "version" is described by the `v2.0.0` specification found at
-<http://semver.org/>.
+<https://semver.org/>.
 
 A leading `"="` or `"v"` character is stripped off and ignored.
 
@@ -130,6 +138,13 @@ the user is indicating that they are aware of the risk.  However, it
 is still not appropriate to assume that they have opted into taking a
 similar risk on the *next* set of prerelease versions.
 
+Note that this behavior can be suppressed (treating all prerelease
+versions as if they were normal versions, for the purpose of range
+matching) by setting the `includePrerelease` flag on the options
+object to any
+[functions](https://github.com/npm/node-semver#functions) that do
+range matching.
+
 #### Prerelease Identifiers
 
 The method `.inc` takes an additional `identifier` string argument that
@@ -268,7 +283,7 @@ logical-or ::= ( ' ' ) * '||' ( ' ' ) *
 range      ::= hyphen | simple ( ' ' simple ) * | ''
 hyphen     ::= partial ' - ' partial
 simple     ::= primitive | partial | tilde | caret
-primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
+primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
 partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
 xr         ::= 'x' | 'X' | '*' | nr
 nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
@@ -283,9 +298,19 @@ part       ::= nr | [-0-9A-Za-z]+
 
 ## Functions
 
-All methods and classes take a final `loose` boolean argument that, if
-true, will be more forgiving about not-quite-valid semver strings.
-The resulting output will always be 100% strict, of course.
+All methods and classes take a final `options` object argument.  All
+options in this object are `false` by default.  The options supported
+are:
+
+- `loose`  Be more forgiving about not-quite-valid semver strings.
+  (Any resulting output will always be 100% strict compliant, of
+  course.)  For backwards compatibility reasons, if the `options`
+  argument is a boolean value instead of an object, it is interpreted
+  to be the `loose` param.
+- `includePrerelease`  Set to suppress the [default
+  behavior](https://github.com/npm/node-semver#prerelease-tags) of
+  excluding prerelease tagged versions from ranges unless they are
+  explicitly opted into.
 
 Strict-mode Comparators and Ranges will be strict about the SemVer
 strings that they parse.
@@ -308,6 +333,8 @@ strings that they parse.
 * `patch(v)`: Return the patch version number.
 * `intersects(r1, r2, loose)`: Return true if the two supplied ranges
   or comparators intersect.
+* `parse(v)`: Attempt to parse a string as a semantic version, returning either
+  a `SemVer` object or `null`.
 
 ### Comparison
 
@@ -344,6 +371,8 @@ strings that they parse.
   that satisfies the range, or `null` if none of them do.
 * `minSatisfying(versions, range)`: Return the lowest version in the list
   that satisfies the range, or `null` if none of them do.
+* `minVersion(range)`: Return the lowest version that can possibly match
+  the given range.
 * `gtr(version, range)`: Return `true` if version is greater than all the
   versions possible in the range.
 * `ltr(version, range)`: Return `true` if version is less than all the
@@ -364,3 +393,19 @@ satisfy the range.
 
 If you want to know if a version satisfies or does not satisfy a
 range, use the `satisfies(version, range)` function.
+
+### Coercion
+
+* `coerce(version)`: 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 remaining characters which satisfy at least a partial semver
+(e.g., `1`, `1.2`, `1.2.3`) up to the max permitted length (256 characters).
+Longer versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).
+All surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes `3.4.0`).
+Only text which lacks digits will fail coercion (`version one` is not valid).
+The maximum  length for any semver component considered for 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 `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`;
+higher value components are invalid (`9999999999999999.4.7.4` is likely invalid).

package/bin/semver

@@ -4,17 +4,28 @@
 // any supplied version is valid and passes all tests.
 
 var argv = process.argv.slice(2)
-  , versions = []
-  , range = []
-  , gt = []
-  , lt = []
-  , eq = []
-  , inc = null
-  , version = require("../package.json").version
-  , loose = false
-  , identifier = undefined
-  , semver = require("../semver")
-  , reverse = false
+
+var versions = []
+
+var range = []
+
+var inc = null
+
+var version = require('../package.json').version
+
+var loose = false
+
+var includePrerelease = false
+
+var coerce = false
+
+var identifier
+
+var semver = require('../semver')
+
+var reverse = false
+
+var options = {}
 
 main()
 
@@ -22,39 +33,45 @@ function main () {
   if (!argv.length) return help()
   while (argv.length) {
     var a = argv.shift()
-    var i = a.indexOf('=')
-    if (i !== -1) {
-      a = a.slice(0, i)
-      argv.unshift(a.slice(i + 1))
+    var indexOfEqualSign = a.indexOf('=')
+    if (indexOfEqualSign !== -1) {
+      a = a.slice(0, indexOfEqualSign)
+      argv.unshift(a.slice(indexOfEqualSign + 1))
     }
     switch (a) {
-      case "-rv": case "-rev": case "--rev": case "--reverse":
+      case '-rv': case '-rev': case '--rev': case '--reverse':
         reverse = true
         break
-      case "-l": case "--loose":
+      case '-l': case '--loose':
         loose = true
         break
-      case "-v": case "--version":
+      case '-p': case '--include-prerelease':
+        includePrerelease = true
+        break
+      case '-v': case '--version':
         versions.push(argv.shift())
         break
-      case "-i": case "--inc": case "--increment":
+      case '-i': case '--inc': case '--increment':
         switch (argv[0]) {
-          case "major": case "minor": case "patch": case "prerelease":
-          case "premajor": case "preminor": case "prepatch":
+          case 'major': case 'minor': case 'patch': case 'prerelease':
+          case 'premajor': case 'preminor': case 'prepatch':
             inc = argv.shift()
             break
           default:
-            inc = "patch"
+            inc = 'patch'
             break
         }
         break
-      case "--preid":
+      case '--preid':
         identifier = argv.shift()
         break
-      case "-r": case "--range":
+      case '-r': case '--range':
         range.push(argv.shift())
         break
-      case "-h": case "--help": case "-?":
+      case '-c': case '--coerce':
+        coerce = true
+        break
+      case '-h': case '--help': case '-?':
         return help()
       default:
         versions.push(a)
@@ -62,16 +79,19 @@ function main () {
     }
   }
 
-  versions = versions.filter(function (v) {
-    return semver.valid(v, loose)
+  var options = { loose: loose, includePrerelease: includePrerelease }
+
+  versions = versions.map(function (v) {
+    return coerce ? (semver.coerce(v) || { version: v }).version : v
+  }).filter(function (v) {
+    return semver.valid(v)
   })
   if (!versions.length) return fail()
-  if (inc && (versions.length !== 1 || range.length))
-    return failInc()
+  if (inc && (versions.length !== 1 || range.length)) { return failInc() }
 
-  for (var i = 0, l = range.length; i < l ; i ++) {
+  for (var i = 0, l = range.length; i < l; i++) {
     versions = versions.filter(function (v) {
-      return semver.satisfies(v, range[i], loose)
+      return semver.satisfies(v, range[i], options)
     })
     if (!versions.length) return fail()
   }
@@ -79,55 +99,62 @@ function main () {
 }
 
 function failInc () {
-  console.error("--inc can only be used on a single version with no range")
+  console.error('--inc can only be used on a single version with no range')
   fail()
 }
 
 function fail () { process.exit(1) }
 
 function success () {
-  var compare = reverse ? "rcompare" : "compare"
+  var compare = reverse ? 'rcompare' : 'compare'
   versions.sort(function (a, b) {
-    return semver[compare](a, b, loose)
+    return semver[compare](a, b, options)
   }).map(function (v) {
-    return semver.clean(v, loose)
+    return semver.clean(v, options)
   }).map(function (v) {
-    return inc ? semver.inc(v, inc, loose, identifier) : v
-  }).forEach(function (v,i,_) { console.log(v) })
+    return inc ? semver.inc(v, inc, options, identifier) : v
+  }).forEach(function (v, i, _) { console.log(v) })
 }
 
 function help () {
-  console.log(["SemVer " + version
-              ,""
-              ,"A JavaScript implementation of the http://semver.org/ specification"
-              ,"Copyright Isaac Z. Schlueter"
-              ,""
-              ,"Usage: semver [options] <version> [<version> [...]]"
-              ,"Prints valid versions sorted by SemVer precedence"
-              ,""
-              ,"Options:"
-              ,"-r --range <range>"
-              ,"        Print versions that match the specified range."
-              ,""
-              ,"-i --increment [<level>]"
-              ,"        Increment a version by the specified level.  Level can"
-              ,"        be one of: major, minor, patch, premajor, preminor,"
-              ,"        prepatch, or prerelease.  Default level is 'patch'."
-              ,"        Only one version may be specified."
-              ,""
-              ,"--preid <identifier>"
-              ,"        Identifier to be used to prefix premajor, preminor,"
-              ,"        prepatch or prerelease version increments."
-              ,""
-              ,"-l --loose"
-              ,"        Interpret versions and ranges loosely"
-              ,""
-              ,"Program exits successfully if any valid version satisfies"
-              ,"all supplied ranges, and prints all satisfying versions."
-              ,""
-              ,"If no satisfying versions are found, then exits failure."
-              ,""
-              ,"Versions are printed in ascending order, so supplying"
-              ,"multiple versions to the utility will just sort them."
-              ].join("\n"))
+  console.log(['SemVer ' + version,
+    '',
+    'A JavaScript implementation of the https://semver.org/ specification',
+    'Copyright Isaac Z. Schlueter',
+    '',
+    'Usage: semver [options] <version> [<version> [...]]',
+    'Prints valid versions sorted by SemVer precedence',
+    '',
+    'Options:',
+    '-r --range <range>',
+    '        Print versions that match the specified range.',
+    '',
+    '-i --increment [<level>]',
+    '        Increment a version by the specified level.  Level can',
+    '        be one of: major, minor, patch, premajor, preminor,',
+    "        prepatch, or prerelease.  Default level is 'patch'.",
+    '        Only one version may be specified.',
+    '',
+    '--preid <identifier>',
+    '        Identifier to be used to prefix premajor, preminor,',
+    '        prepatch or prerelease version increments.',
+    '',
+    '-l --loose',
+    '        Interpret versions and ranges loosely',
+    '',
+    '-p --include-prerelease',
+    '        Always include prerelease versions in range matching',
+    '',
+    '-c --coerce',
+    '        Coerce a string into SemVer if possible',
+    '        (does not imply --loose)',
+    '',
+    'Program exits successfully if any valid version satisfies',
+    'all supplied ranges, and prints all satisfying versions.',
+    '',
+    'If no satisfying versions are found, then exits failure.',
+    '',
+    'Versions are printed in ascending order, so supplying',
+    'multiple versions to the utility will just sort them.'
+  ].join('\n'))
 }

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "semver",
-  "version": "5.4.1",
+  "version": "5.7.0",
   "description": "The semantic version parser used by npm.",
   "main": "semver.js",
   "scripts": {
-    "test": "tap test/*.js --cov -J"
+    "test": "tap",
+    "preversion": "npm test",
+    "postversion": "npm publish",
+    "postpublish": "git push origin --all; git push origin --tags"
   },
   "devDependencies": {
-    "tap": "^10.7.0"
+    "tap": "^13.0.0-rc.18"
   },
   "license": "ISC",
   "repository": "https://github.com/npm/node-semver",
@@ -18,5 +21,8 @@
     "bin",
     "range.bnf",
     "semver.js"
-  ]
+  ],
+  "tap": {
+    "check-coverage": true
+  }
 }

package/range.bnf

@@ -3,10 +3,10 @@ logical-or ::= ( ' ' ) * '||' ( ' ' ) *
 range      ::= hyphen | simple ( ' ' simple ) * | ''
 hyphen     ::= partial ' - ' partial
 simple     ::= primitive | partial | tilde | caret
-primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
+primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
 partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
 xr         ::= 'x' | 'X' | '*' | nr
-nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
+nr         ::= '0' | [1-9] ( [0-9] ) *
 tilde      ::= '~' partial
 caret      ::= '^' partial
 qualifier  ::= ( '-' pre )? ( '+' build )?