semver 5.0.3 → 5.3.0

package/README.md

@@ -4,6 +4,8 @@ semver(1) -- The semantic versioner for npm
 ## Usage
 
     $ npm install semver
+    $ node
+    var semver = require('semver')
 
     semver.valid('1.2.3') // '1.2.3'
     semver.valid('a.b.c') // null
@@ -16,18 +18,35 @@ As a command-line utility:
 
     $ semver -h
 
-    Usage: semver <version> [<version> [...]] [-r <range> | -i <inc> | --preid <identifier> | -l | -rv]
-    Test if version(s) satisfy the supplied range(s), and sort them.
+    SemVer 5.1.0
 
-    Multiple versions or ranges may be supplied, unless increment
-    option is specified.  In that case, only a single version may
-    be used, and it is incremented by the specified level
+    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 versions are valid, or ranges are not satisfied,
-    then exits failure.
+    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.
@@ -107,7 +126,7 @@ The method `.inc` takes an additional `identifier` string argument that
 will append the value of the string as a prerelease identifier:
 
 ```javascript
-> semver.inc('1.2.3', 'pre', 'beta')
+> semver.inc('1.2.3', 'prerelease', 'beta')
 '1.2.4-beta.0'
 ```
 
@@ -228,6 +247,30 @@ zero.
 * `^1.x` := `>=1.0.0 <2.0.0`
 * `^0.x` := `>=0.0.0 <1.0.0`
 
+### Range Grammar
+
+Putting all this together, here is a Backus-Naur grammar for ranges,
+for the benefit of parser authors:
+
+```bnf
+range-set  ::= range ( logical-or range ) *
+logical-or ::= ( ' ' ) * '||' ( ' ' ) *
+range      ::= hyphen | simple ( ' ' simple ) * | ''
+hyphen     ::= partial ' - ' partial
+simple     ::= primitive | partial | tilde | caret
+primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
+partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
+xr         ::= 'x' | 'X' | '*' | nr
+nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
+tilde      ::= '~' partial
+caret      ::= '^' partial
+qualifier  ::= ( '-' pre )? ( '+' build )?
+pre        ::= parts
+build      ::= parts
+parts      ::= part ( '.' part ) *
+part       ::= nr | [-0-9A-Za-z]+
+```
+
 ## Functions
 
 All methods and classes take a final `loose` boolean argument that, if
@@ -248,6 +291,8 @@ strings that they parse.
     same as `prepatch`. It increments the patch version, then makes a
     prerelease. If the input version is already a prerelease it simply
     increments it.
+* `prerelease(v)`: Returns an array of prerelease components, or null
+  if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]`
 * `major(v)`: Return the major version number.
 * `minor(v)`: Return the minor version number.
 * `patch(v)`: Return the patch version number.
@@ -282,6 +327,8 @@ strings that they parse.
   range.
 * `maxSatisfying(versions, range)`: Return the highest version in the list
   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.
 * `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

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "semver",
-  "version": "5.0.3",
+  "version": "5.3.0",
   "description": "The semantic version parser used by npm.",
   "main": "semver.js",
   "scripts": {
     "test": "tap test/*.js"
   },
   "devDependencies": {
-    "tap": "^1.3.4"
+    "tap": "^2.0.0"
   },
   "license": "ISC",
   "repository": "https://github.com/npm/node-semver",
   "bin": {
     "semver": "./bin/semver"
-  }
+  },
+  "files": [
+    "bin",
+    "range.bnf",
+    "semver.js"
+  ]
 }

package/range.bnf

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

package/semver.js

@@ -314,9 +314,9 @@ function SemVer(version, loose) {
   else
     this.prerelease = m[4].split('.').map(function(id) {
       if (/^[0-9]+$/.test(id)) {
-        var num = +id
+        var num = +id;
         if (num >= 0 && num < MAX_SAFE_INTEGER)
-          return num
+          return num;
       }
       return id;
     });
@@ -332,10 +332,6 @@ SemVer.prototype.format = function() {
   return this.version;
 };
 
-SemVer.prototype.inspect = function() {
-  return '<SemVer "' + this + '">';
-};
-
 SemVer.prototype.toString = function() {
   return this.version;
 };
@@ -692,10 +688,6 @@ Comparator.prototype.parse = function(comp) {
     this.semver = new SemVer(m[2], this.loose);
 };
 
-Comparator.prototype.inspect = function() {
-  return '<SemVer Comparator "' + this + '">';
-};
-
 Comparator.prototype.toString = function() {
   return this.value;
 };
@@ -739,10 +731,6 @@ function Range(range, loose) {
   this.format();
 }
 
-Range.prototype.inspect = function() {
-  return '<SemVer Range "' + this.range + '">';
-};
-
 Range.prototype.format = function() {
   this.range = this.set.map(function(comps) {
     return comps.join(' ').trim();
@@ -848,7 +836,7 @@ function replaceTilde(comp, loose) {
     else if (isX(m))
       ret = '>=' + M + '.0.0 <' + (+M + 1) + '.0.0';
     else if (isX(p))
-      // ~1.2 == >=1.2.0- <1.3.0-
+      // ~1.2 == >=1.2.0 <1.3.0
       ret = '>=' + M + '.' + m + '.0 <' + M + '.' + (+m + 1) + '.0';
     else if (pr) {
       debug('replaceTilde pr', pr);
@@ -978,11 +966,11 @@ function replaceXRange(comp, loose) {
       } else if (gtlt === '<=') {
         // <=0.7.x is actually <0.8.0, since any 0.7.x should
         // pass.  Similarly, <=7.x is actually <8.0.0, etc.
-        gtlt = '<'
+        gtlt = '<';
         if (xm)
-          M = +M + 1
+          M = +M + 1;
         else
-          m = +m + 1
+          m = +m + 1;
       }
 
       ret = gtlt + M + '.' + m + '.' + p;
@@ -1106,6 +1094,15 @@ function maxSatisfying(versions, range, loose) {
   })[0] || null;
 }
 
+exports.minSatisfying = minSatisfying;
+function minSatisfying(versions, range, loose) {
+  return versions.filter(function(version) {
+    return satisfies(version, range, loose);
+  }).sort(function(a, b) {
+    return compare(a, b, loose);
+  })[0] || null;
+}
+
 exports.validRange = validRange;
 function validRange(range, loose) {
   try {
@@ -1198,3 +1195,9 @@ function outside(version, range, hilo, loose) {
   }
   return true;
 }
+
+exports.prerelease = prerelease;
+function prerelease(version, loose) {
+  var parsed = parse(version, loose);
+  return (parsed && parsed.prerelease.length) ? parsed.prerelease : null;
+}

package/.npmignore

@@ -1,4 +0,0 @@
-node_modules/
-coverage/
-.nyc_output/
-nyc_output/

package/.travis.yml

@@ -1,5 +0,0 @@
-language: node_js
-node_js:
-  - '0.10'
-  - '0.12'
-  - 'iojs'

package/test/big-numbers.js

@@ -1,31 +0,0 @@
-var test = require('tap').test
-var semver = require('../')
-
-test('long version is too long', function (t) {
-  var v = '1.2.' + new Array(256).join('1')
-  t.throws(function () {
-    new semver.SemVer(v)
-  })
-  t.equal(semver.valid(v, false), null)
-  t.equal(semver.valid(v, true), null)
-  t.equal(semver.inc(v, 'patch'), null)
-  t.end()
-})
-
-test('big number is like too long version', function (t) {
-  var v = '1.2.' + new Array(100).join('1')
-  t.throws(function () {
-    new semver.SemVer(v)
-  })
-  t.equal(semver.valid(v, false), null)
-  t.equal(semver.valid(v, true), null)
-  t.equal(semver.inc(v, 'patch'), null)
-  t.end()
-})
-
-test('parsing null does not throw', function (t) {
-  t.equal(semver.parse(null), null)
-  t.equal(semver.parse({}), null)
-  t.equal(semver.parse(new semver.SemVer('1.2.3')).version, '1.2.3')
-  t.end()
-})

package/test/clean.js

@@ -1,29 +0,0 @@
-var tap = require('tap');
-var test = tap.test;
-var semver = require('../semver.js');
-var clean = semver.clean;
-
-test('\nclean tests', function(t) {
-	// [range, version]
-	// Version should be detectable despite extra characters
-	[
-		['1.2.3', '1.2.3'],
-		[' 1.2.3 ', '1.2.3'],
-		[' 1.2.3-4 ', '1.2.3-4'],
-		[' 1.2.3-pre ', '1.2.3-pre'],
-		['  =v1.2.3   ', '1.2.3'],
-		['v1.2.3', '1.2.3'],
-		[' v1.2.3 ', '1.2.3'],
-		['\t1.2.3', '1.2.3'],
-		['>1.2.3', null],
-		['~1.2.3', null],
-		['<=1.2.3', null],
-		['1.2.x', null]
-	].forEach(function(tuple) {
-			var range = tuple[0];
-			var version = tuple[1];
-			var msg = 'clean(' + range + ') = ' + version;
-			t.equal(clean(range), version, msg);
-		});
-	t.end();
-});

package/test/gtr.js

@@ -1,173 +0,0 @@
-var tap = require('tap');
-var test = tap.test;
-var semver = require('../semver.js');
-var gtr = semver.gtr;
-
-test('\ngtr tests', function(t) {
-  // [range, version, loose]
-  // Version should be greater than range
-  [
-    ['~1.2.2', '1.3.0'],
-    ['~0.6.1-1', '0.7.1-1'],
-    ['1.0.0 - 2.0.0', '2.0.1'],
-    ['1.0.0', '1.0.1-beta1'],
-    ['1.0.0', '2.0.0'],
-    ['<=2.0.0', '2.1.1'],
-    ['<=2.0.0', '3.2.9'],
-    ['<2.0.0', '2.0.0'],
-    ['0.1.20 || 1.2.4', '1.2.5'],
-    ['2.x.x', '3.0.0'],
-    ['1.2.x', '1.3.0'],
-    ['1.2.x || 2.x', '3.0.0'],
-    ['2.*.*', '5.0.1'],
-    ['1.2.*', '1.3.3'],
-    ['1.2.* || 2.*', '4.0.0'],
-    ['2', '3.0.0'],
-    ['2.3', '2.4.2'],
-    ['~2.4', '2.5.0'], // >=2.4.0 <2.5.0
-    ['~2.4', '2.5.5'],
-    ['~>3.2.1', '3.3.0'], // >=3.2.1 <3.3.0
-    ['~1', '2.2.3'], // >=1.0.0 <2.0.0
-    ['~>1', '2.2.4'],
-    ['~> 1', '3.2.3'],
-    ['~1.0', '1.1.2'], // >=1.0.0 <1.1.0
-    ['~ 1.0', '1.1.0'],
-    ['<1.2', '1.2.0'],
-    ['< 1.2', '1.2.1'],
-    ['1', '2.0.0beta', true],
-    ['~v0.5.4-pre', '0.6.0'],
-    ['~v0.5.4-pre', '0.6.1-pre'],
-    ['=0.7.x', '0.8.0'],
-    ['=0.7.x', '0.8.0-asdf'],
-    ['<0.7.x', '0.7.0'],
-    ['~1.2.2', '1.3.0'],
-    ['1.0.0 - 2.0.0', '2.2.3'],
-    ['1.0.0', '1.0.1'],
-    ['<=2.0.0', '3.0.0'],
-    ['<=2.0.0', '2.9999.9999'],
-    ['<=2.0.0', '2.2.9'],
-    ['<2.0.0', '2.9999.9999'],
-    ['<2.0.0', '2.2.9'],
-    ['2.x.x', '3.1.3'],
-    ['1.2.x', '1.3.3'],
-    ['1.2.x || 2.x', '3.1.3'],
-    ['2.*.*', '3.1.3'],
-    ['1.2.*', '1.3.3'],
-    ['1.2.* || 2.*', '3.1.3'],
-    ['2', '3.1.2'],
-    ['2.3', '2.4.1'],
-    ['~2.4', '2.5.0'], // >=2.4.0 <2.5.0
-    ['~>3.2.1', '3.3.2'], // >=3.2.1 <3.3.0
-    ['~1', '2.2.3'], // >=1.0.0 <2.0.0
-    ['~>1', '2.2.3'],
-    ['~1.0', '1.1.0'], // >=1.0.0 <1.1.0
-    ['<1', '1.0.0'],
-    ['1', '2.0.0beta', true],
-    ['<1', '1.0.0beta', true],
-    ['< 1', '1.0.0beta', true],
-    ['=0.7.x', '0.8.2'],
-    ['<0.7.x', '0.7.2']
-  ].forEach(function(tuple) {
-    var range = tuple[0];
-    var version = tuple[1];
-    var loose = tuple[2] || false;
-    var msg = 'gtr(' + version + ', ' + range + ', ' + loose + ')';
-    t.ok(gtr(version, range, loose), msg);
-  });
-  t.end();
-});
-
-test('\nnegative gtr tests', function(t) {
-  // [range, version, loose]
-  // Version should NOT be greater than range
-  [
-    ['~0.6.1-1', '0.6.1-1'],
-    ['1.0.0 - 2.0.0', '1.2.3'],
-    ['1.0.0 - 2.0.0', '0.9.9'],
-    ['1.0.0', '1.0.0'],
-    ['>=*', '0.2.4'],
-    ['', '1.0.0', true],
-    ['*', '1.2.3'],
-    ['*', 'v1.2.3-foo'],
-    ['>=1.0.0', '1.0.0'],
-    ['>=1.0.0', '1.0.1'],
-    ['>=1.0.0', '1.1.0'],
-    ['>1.0.0', '1.0.1'],
-    ['>1.0.0', '1.1.0'],
-    ['<=2.0.0', '2.0.0'],
-    ['<=2.0.0', '1.9999.9999'],
-    ['<=2.0.0', '0.2.9'],
-    ['<2.0.0', '1.9999.9999'],
-    ['<2.0.0', '0.2.9'],
-    ['>= 1.0.0', '1.0.0'],
-    ['>=  1.0.0', '1.0.1'],
-    ['>=   1.0.0', '1.1.0'],
-    ['> 1.0.0', '1.0.1'],
-    ['>  1.0.0', '1.1.0'],
-    ['<=   2.0.0', '2.0.0'],
-    ['<= 2.0.0', '1.9999.9999'],
-    ['<=  2.0.0', '0.2.9'],
-    ['<    2.0.0', '1.9999.9999'],
-    ['<\t2.0.0', '0.2.9'],
-    ['>=0.1.97', 'v0.1.97'],
-    ['>=0.1.97', '0.1.97'],
-    ['0.1.20 || 1.2.4', '1.2.4'],
-    ['0.1.20 || >1.2.4', '1.2.4'],
-    ['0.1.20 || 1.2.4', '1.2.3'],
-    ['0.1.20 || 1.2.4', '0.1.20'],
-    ['>=0.2.3 || <0.0.1', '0.0.0'],
-    ['>=0.2.3 || <0.0.1', '0.2.3'],
-    ['>=0.2.3 || <0.0.1', '0.2.4'],
-    ['||', '1.3.4'],
-    ['2.x.x', '2.1.3'],
-    ['1.2.x', '1.2.3'],
-    ['1.2.x || 2.x', '2.1.3'],
-    ['1.2.x || 2.x', '1.2.3'],
-    ['x', '1.2.3'],
-    ['2.*.*', '2.1.3'],
-    ['1.2.*', '1.2.3'],
-    ['1.2.* || 2.*', '2.1.3'],
-    ['1.2.* || 2.*', '1.2.3'],
-    ['1.2.* || 2.*', '1.2.3'],
-    ['*', '1.2.3'],
-    ['2', '2.1.2'],
-    ['2.3', '2.3.1'],
-    ['~2.4', '2.4.0'], // >=2.4.0 <2.5.0
-    ['~2.4', '2.4.5'],
-    ['~>3.2.1', '3.2.2'], // >=3.2.1 <3.3.0
-    ['~1', '1.2.3'], // >=1.0.0 <2.0.0
-    ['~>1', '1.2.3'],
-    ['~> 1', '1.2.3'],
-    ['~1.0', '1.0.2'], // >=1.0.0 <1.1.0
-    ['~ 1.0', '1.0.2'],
-    ['>=1', '1.0.0'],
-    ['>= 1', '1.0.0'],
-    ['<1.2', '1.1.1'],
-    ['< 1.2', '1.1.1'],
-    ['1', '1.0.0beta', true],
-    ['~v0.5.4-pre', '0.5.5'],
-    ['~v0.5.4-pre', '0.5.4'],
-    ['=0.7.x', '0.7.2'],
-    ['>=0.7.x', '0.7.2'],
-    ['=0.7.x', '0.7.0-asdf'],
-    ['>=0.7.x', '0.7.0-asdf'],
-    ['<=0.7.x', '0.6.2'],
-    ['>0.2.3 >0.2.4 <=0.2.5', '0.2.5'],
-    ['>=0.2.3 <=0.2.4', '0.2.4'],
-    ['1.0.0 - 2.0.0', '2.0.0'],
-    ['^1', '0.0.0-0'],
-    ['^3.0.0', '2.0.0'],
-    ['^1.0.0 || ~2.0.1', '2.0.0'],
-    ['^0.1.0 || ~3.0.1 || 5.0.0', '3.2.0'],
-    ['^0.1.0 || ~3.0.1 || 5.0.0', '1.0.0beta', true],
-    ['^0.1.0 || ~3.0.1 || 5.0.0', '5.0.0-0', true],
-    ['^0.1.0 || ~3.0.1 || >4 <=5.0.0', '3.5.0']
-  ].forEach(function(tuple) {
-    var range = tuple[0];
-    var version = tuple[1];
-    var loose = tuple[2] || false;
-    var msg = '!gtr(' + version + ', ' + range + ', ' + loose + ')';
-    t.notOk(gtr(version, range, loose), msg);
-  });
-  t.end();
-});