url: add join method

doc/api/url.markdown

@@ -125,3 +125,11 @@ an anchor tag.  Examples:
     url.resolve('/one/two/three', 'four')         // '/one/two/four'
     url.resolve('http://example.com/', '/one')    // 'http://example.com/one'
     url.resolve('http://example.com/one', '/two') // 'http://example.com/two'
+
+## url.join(base, [path1][, path2][, ...])
+
+Take any number of paths as an argument, join them together, and resolve the results of the join with the base URL as a browser would for an anchor tag. Examples:
+
+    url.join('http://example.com', '/a', 'b');      // 'http://example.com/a/b'
+    url.join('http://example.com', 'a', '../b');    // 'http://example.com/b'
+    url.join('https://example.com', '1', '2', '3'); // 'http://example.com/1/2/3'

lib/url.js

@@ -1,8 +1,10 @@
 'use strict';
 
 const punycode = require('punycode');
+const posix = require('path').posix;
 
 exports.parse = urlParse;
+exports.join = urlJoin;
 exports.resolve = urlResolve;
 exports.resolveObject = urlResolveObject;
 exports.format = urlFormat;
@@ -418,6 +420,18 @@ Url.prototype.format = function() {
   return protocol + host + pathname + search + hash;
 };
 
+function urlJoin(/**/) {
+  let url = urlParse(arguments[0], false, true);
+  return url.join.apply(url, arguments);
+}
+
+Url.prototype.join = function(/**/) {
+  let args = Array.prototype.slice.call(arguments);
+  let path = args.splice(1, args.length - 1);
+  let relative = posix.join.apply(null, path);
+  return this.resolve(relative);
+};
+
 function urlResolve(source, relative) {
   return urlParse(source, false, true).resolve(relative);
 }

test/parallel/test-url.js

@@ -1145,6 +1145,32 @@ for (var u in formatTests) {
                '\nactual: ' + actualObj);
 }
 
+//
+// {attempt: array of args, expected: string}
+//
+var joinTests = [
+  {
+    attempt: ['http://google.com', 'search', '/this', '//nothing', '../page'],
+    expected: 'http://google.com/search/this/page'
+  },
+  {
+    attempt: ['http://npmjs.com', 'my', '/favorite', 'module'],
+    expected: 'http://npmjs.com/my/favorite/module'
+  },
+  {
+    attempt: ['https://example.org', 'page'],
+    expected: 'https://example.org/page'
+  }
+];
+
+joinTests.forEach(function (joinTest) {
+  var a = url.join.apply(null, joinTest.attempt);
+  var e = joinTest.expected;
+  assert.equal(a, e,
+               'join(' + joinTest.attempt + ') == ' + e +
+               '\n actual=' + a);
+});
+
 /*
  [from, path, expected]
 */