document differences to URL() and 'special scheme'

README.md

@@ -4,6 +4,14 @@
 
 Lightweight library to build an absolute URL from a base URL and a relative URL, written from [the spec (RFC 1808)](https://tools.ietf.org/html/rfc1808). Initially part of [HLS.JS](https://github.com/dailymotion/hls.js).
 
+## Differences to JS `URL()`
+
+The JS [URL()](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) function also lets you calculate a new URL from a base and relative one.
+
+That uses the [URL Living Standard](https://url.spec.whatwg.org/) which is slightly different to [RFC 1808](https://tools.ietf.org/html/rfc1808) that this library implements.
+
+One of the key differences is that the [URL Living Standard](https://url.spec.whatwg.org/) has the concept of a ['special url'](https://url.spec.whatwg.org/#is-special) and ['special scheme'](https://url.spec.whatwg.org/#special-scheme). For these special URL's, such as a URL with the `http` scheme, they normalise them in a way that results in `http:///example.com/something` becoming `http://example.com/something`. This library does not do that and [`parseURL()`](#parseurlurl) would give you `//` as the `netLoc` and `/example.com` as the path.
+
 ## Methods
 
 ### `buildAbsoluteURL(baseURL, relativeURL, opts={})`

test/__snapshots__/url-toolkit.js.snap

@@ -462,6 +462,28 @@ Object {
 }
 `;
 
+exports[`url toolkit works with a selection of valid urls "http:///example.com/a/" + "../../b" {} 1`] = `
+Object {
+  "fragment": "",
+  "netLoc": "//",
+  "params": "",
+  "path": "/example.com/a/",
+  "query": "",
+  "scheme": "http:",
+}
+`;
+
+exports[`url toolkit works with a selection of valid urls "http:///example.com/a/" + "../../b" {} 2`] = `
+Object {
+  "fragment": "",
+  "netLoc": "",
+  "params": "",
+  "path": "../../b",
+  "query": "",
+  "scheme": "",
+}
+`;
+
 exports[`url toolkit works with a selection of valid urls "http://[0:0:0:0::0]/a/b.c" + "d" {} 1`] = `
 Object {
   "fragment": "",

test/url-toolkit.js

@@ -294,6 +294,14 @@ describe('url toolkit', () => {
     test('http://[0:0:0:0::0]/a/b.c', 'd', 'http://[0:0:0:0::0]/a/d');
 
     test('http://example.com/', 'a#\nb', 'http://example.com/a#\nb');
+
+    // in the URL living standard (https://url.spec.whatwg.org/)
+    // `http` is a 'special scheme', and that results in
+    // the `///` becoming `//`, meaning `netLoc` would essentially be
+    // `//example.com` instead of `//`
+    // This library is specifically RFC 1808, which does not have these
+    // special cases.
+    test('http:///example.com/a/', '../../b', 'http:///b');
   });
 });