process: add release.compareVersion(str) functionality

doc/api/process.md

@@ -1554,6 +1554,18 @@ Perform a SemVer comparison to the release version.
   version, `0` if the given version matches the process version, and `-1`
   if the given version is greater than the release version.
 
+## process.release.compareVersion(version)
+<!-- YAML
+added: REPLACEME
+-->
+
+Perform a SemVer comparison to the release version.
+
+* `version` {string} The semver version to compare.
+* Returns: {number} `1` if the given version is lower than the current release
+  version, `0` if the given version matches the process version, and `-1`
+  if the given version is greater than the release version.
+
 ## process.send(message[, sendHandle[, options]][, callback])
 <!-- YAML
 added: v0.5.9

lib/internal/process.js

@@ -6,8 +6,10 @@ const {
     ERR_ASSERTION,
     ERR_CPU_USAGE,
     ERR_INVALID_ARG_TYPE,
+    ERR_INVALID_ARG_VALUE,
     ERR_INVALID_ARRAY_LENGTH,
     ERR_INVALID_OPT_VALUE,
+    ERR_OUT_OF_RANGE,
     ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET,
     ERR_UNKNOWN_SIGNAL
   }
@@ -291,15 +293,43 @@ function setupCompareVersion() {
     prereleaseTag,
   } = process.release;
 
-  process.release.compareVersion = (major, minor, patch, tag) => {
-    if (typeof major !== 'number')
-      throw new ERR_INVALID_ARG_TYPE('major', 'number', major);
-    if (typeof minor !== 'number')
-      throw new ERR_INVALID_ARG_TYPE('minor', 'number', minor);
-    if (typeof patch !== 'number')
-      throw new ERR_INVALID_ARG_TYPE('patch', 'number', patch);
-    if (tag !== undefined && typeof tag !== 'string')
-      throw new ERR_INVALID_ARG_TYPE('tag', 'string', tag);
+  process.release.compareVersion = function(major, minor, patch, tag) {
+    if (arguments.length === 1 && typeof major === 'string') {
+      const [start, ...end] = major.split('-');
+      tag = end.join('-');
+      const chunks = start.split('.');
+      if (chunks.length !== 3) {
+        throw new ERR_INVALID_ARG_VALUE('version',
+                                        major,
+                                        'is not a valid Semantic Version');
+      }
+      [major, minor, patch] = chunks.map((chunk) => {
+        const num = Number(chunk);
+        if (Number.isNaN(num) ||
+            chunk === '' ||
+            chunk.length > 1 && chunk.startsWith('0')) {
+          throw new ERR_INVALID_ARG_VALUE('version',
+                                          major,
+                                          'is not a valid Semantic Version');
+        }
+        return num;
+      });
+    } else {
+      if (typeof major !== 'number')
+        throw new ERR_INVALID_ARG_TYPE('major', 'number', major);
+      if (typeof minor !== 'number')
+        throw new ERR_INVALID_ARG_TYPE('minor', 'number', minor);
+      if (typeof patch !== 'number')
+        throw new ERR_INVALID_ARG_TYPE('patch', 'number', patch);
+      if (tag !== undefined && typeof tag !== 'string')
+        throw new ERR_INVALID_ARG_TYPE('tag', 'string', tag);
+    }
+    if (major < 0)
+      throw new ERR_OUT_OF_RANGE('major', '>= 0', major);
+    if (minor < 0)
+      throw new ERR_OUT_OF_RANGE('minor', '>= 0', minor);
+    if (patch < 0)
+      throw new ERR_OUT_OF_RANGE('patch', '>= 0', patch);
 
     if (major > majorVersion)
       return -1;
@@ -315,8 +345,11 @@ function setupCompareVersion() {
       return -1;
     if (patch < patchVersion)
       return 1;
-    if (prereleaseTag)
-      return prereleaseTag === tag ? 0 : 1;
+    if (prereleaseTag) {
+      if (prereleaseTag === tag)
+        return 0;
+      return prereleaseTag < tag ? -1 : 1;
+    }
     if (tag)
       return -1;
 

test/parallel/test-process-release.js

@@ -1,13 +1,13 @@
 'use strict';
 
-const common = require('../common');
+require('../common');
 
 const assert = require('assert');
 const versionParts = process.versions.node.split('.');
 
 assert.strictEqual(process.release.name, 'node');
 
-// it's expected that future LTS release lines will have additional
+// It's expected that future LTS release lines will have additional
 // branches in here
 if (versionParts[0] === '4' && versionParts[1] >= 2) {
   assert.strictEqual(process.release.lts, 'Argon');
@@ -27,31 +27,84 @@ const {
   compareVersion,
 } = process.release;
 
-assert.strictEqual(compareVersion(major, minor, patch, tag), 0);
+[
+  [major, minor, patch, tag, 0],
+  [major + 1, minor, patch, tag, -1],
+  [major - 1, minor, patch, tag, 1],
+  [major, minor + 1, patch, tag, -1],
+  [major, minor - 1, patch, tag, 1],
+  [major, minor, patch + 1, tag, -1],
+  [major, minor, patch - 1, tag, 1]
+].forEach(([major, minor, patch, tag, expected]) => {
+  // Skip invalid entries.
+  if (major < 0 || minor < 0 || patch < 0)
+    return;
+  assert.strictEqual(compareVersion(major, minor, patch, tag), expected);
+  const semverStr = `${major}.${minor}.${patch}${tag ? `-${tag}` : ''}`;
+  assert.strictEqual(compareVersion(semverStr), expected);
+});
 
-assert.strictEqual(compareVersion(major + 1, minor, patch, tag), -1);
-assert.strictEqual(compareVersion(major - 1, minor, patch, tag), 1);
-
-assert.strictEqual(compareVersion(major, minor + 1, patch, tag), -1);
-assert.strictEqual(compareVersion(major, minor - 1, patch, tag), 1);
-
-assert.strictEqual(compareVersion(major, minor, patch + 1, tag), -1);
-assert.strictEqual(compareVersion(major, minor, patch - 1, tag), 1);
-
-if (tag)
+if (tag) {
   assert.strictEqual(compareVersion(major, minor, patch), 1);
-else
-  assert.strictEqual(compareVersion(major, minor, patch, 'notrealtag'), -1);
-
-for (const args of [
-  ['', 0, 0, ''],
-  [0, '', 0, ''],
-  [0, 0, '', ''],
-  [0, 0, 0, 0],
-]) {
-  common.expectsError(() => {
+  assert.strictEqual(compareVersion(`${major}.${minor}.${patch}`), 1);
+  assert.strictEqual(compareVersion(major, minor, patch, `${tag}-fake`), -1);
+  assert.strictEqual(
+    compareVersion(major, minor, patch, `${tag.slice(0, -1)}`), 1);
+} else {
+  assert.strictEqual(compareVersion(major, minor, patch, 'fake-tag'), -1);
+  assert.strictEqual(compareVersion(`${major}.${minor}.${patch}-fake-tag`), -1);
+  assert.strictEqual(compareVersion(major, minor, patch), 0);
+}
+
+[
+  [['1', 0, 0, ''], 'major', 'string'],
+  [[0, '1', 0, ''], 'minor', 'string'],
+  [[0, 0, '1', ''], 'patch', 'string'],
+  [[0, 0, 0, 1], 'tag', 'number'],
+  [[0, 0, 0, null], 'tag', 'object'],
+].forEach(([args, argName, receivedType]) => {
+  const expectedType = argName === 'tag' ? 'string' : 'number';
+  assert.throws(() => {
     compareVersion(...args);
   }, {
     code: 'ERR_INVALID_ARG_TYPE',
+    name: 'TypeError [ERR_INVALID_ARG_TYPE]',
+    message: `The "${argName}" argument must be of type ${expectedType}. ` +
+             `Received type ${receivedType}`
   });
-}
+});
+
+[
+  [-1, 0, 0, 'major'],
+  [0, -1, 0, 'minor'],
+  [0, 0, -1, 'patch'],
+].forEach(([major, minor, patch, expected]) => {
+  assert.throws(() => {
+    compareVersion(major, minor, patch);
+  }, {
+    code: 'ERR_OUT_OF_RANGE',
+    name: 'RangeError [ERR_OUT_OF_RANGE]',
+    message: `The value of "${expected}" is out of range. ` +
+             'It must be >= 0. Received -1'
+  });
+});
+
+[
+  '1a.0.0',
+  '1.0a.0',
+  '1.0.0a',
+  '1.0.0.0',
+  '01.0.0',
+  '1.01.0',
+  '1.0',
+  '1..0',
+].forEach((version) => {
+  assert.throws(() => {
+    compareVersion(version);
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+    name: 'TypeError [ERR_INVALID_ARG_VALUE]',
+    message: "The argument 'version' is not a valid Semantic Version. " +
+             `Received '${version}'`
+  });
+});