whatwg-url 5.0.0 → 7.1.0

package/README.md

@@ -2,29 +2,32 @@
 
 whatwg-url is a full implementation of the WHATWG [URL Standard](https://url.spec.whatwg.org/). It can be used standalone, but it also exposes a lot of the internal algorithms that are useful for integrating a URL parser into a project like [jsdom](https://github.com/tmpvar/jsdom).
 
-## Current Status
+## Specification conformance
 
-whatwg-url is currently up to date with the URL spec up to commit [a62223](https://github.com/whatwg/url/commit/a622235308342c9adc7fc2fd1659ff059f7d5e2a).
+whatwg-url is currently up to date with the URL spec up to commit [7ae1c69](https://github.com/whatwg/url/commit/7ae1c691c96f0d82fafa24c33aa1e8df9ffbf2bc).
+
+For `file:` URLs, whose [origin is left unspecified](https://url.spec.whatwg.org/#concept-url-origin), whatwg-url chooses to use a new opaque origin (which serializes to `"null"`).
 
 ## API
 
-### The `URL` Constructor
+### The `URL` and `URLSearchParams` classes
 
-The main API is the [`URL`](https://url.spec.whatwg.org/#url) export, which follows the spec's behavior in all ways (including e.g. `USVString` conversion). Most consumers of this library will want to use this.
+The main API is provided by the [`URL`](https://url.spec.whatwg.org/#url-class) and [`URLSearchParams`](https://url.spec.whatwg.org/#interface-urlsearchparams) exports, which follows the spec's behavior in all ways (including e.g. `USVString` conversion). Most consumers of this library will want to use these.
 
 ### Low-level URL Standard API
 
-The following methods are exported for use by places like jsdom that need to implement things like [`HTMLHyperlinkElementUtils`](https://html.spec.whatwg.org/#htmlhyperlinkelementutils). They operate on or return an "internal URL" or ["URL record"](https://url.spec.whatwg.org/#concept-url) type.
+The following methods are exported for use by places like jsdom that need to implement things like [`HTMLHyperlinkElementUtils`](https://html.spec.whatwg.org/#htmlhyperlinkelementutils). They mostly operate on or return an "internal URL" or ["URL record"](https://url.spec.whatwg.org/#concept-url) type.
 
 - [URL parser](https://url.spec.whatwg.org/#concept-url-parser): `parseURL(input, { baseURL, encodingOverride })`
 - [Basic URL parser](https://url.spec.whatwg.org/#concept-basic-url-parser): `basicURLParse(input, { baseURL, encodingOverride, url, stateOverride })`
 - [URL serializer](https://url.spec.whatwg.org/#concept-url-serializer): `serializeURL(urlRecord, excludeFragment)`
 - [Host serializer](https://url.spec.whatwg.org/#concept-host-serializer): `serializeHost(hostFromURLRecord)`
 - [Serialize an integer](https://url.spec.whatwg.org/#serialize-an-integer): `serializeInteger(number)`
-- [Origin](https://url.spec.whatwg.org/#concept-url-origin) [serializer](https://html.spec.whatwg.org/multipage/browsers.html#serialization-of-an-origin): `serializeURLOrigin(urlRecord)`
+- [Origin](https://url.spec.whatwg.org/#concept-url-origin) [serializer](https://html.spec.whatwg.org/multipage/origin.html#ascii-serialisation-of-an-origin): `serializeURLOrigin(urlRecord)`
 - [Set the username](https://url.spec.whatwg.org/#set-the-username): `setTheUsername(urlRecord, usernameString)`
 - [Set the password](https://url.spec.whatwg.org/#set-the-password): `setThePassword(urlRecord, passwordString)`
 - [Cannot have a username/password/port](https://url.spec.whatwg.org/#cannot-have-a-username-password-port): `cannotHaveAUsernamePasswordPort(urlRecord)`
+- [Percent decode](https://url.spec.whatwg.org/#percent-decode): `percentDecode(buffer)`
 
 The `stateOverride` parameter is one of the following strings:
 
@@ -64,4 +67,32 @@ The URL record type has the following API:
 
 These properties should be treated with care, as in general changing them will cause the URL record to be in an inconsistent state until the appropriate invocation of `basicURLParse` is used to fix it up. You can see examples of this in the URL Standard, where there are many step sequences like "4. Set context object’s url’s fragment to the empty string. 5. Basic URL parse _input_ with context object’s url as _url_ and fragment state as _state override_." In between those two steps, a URL record is in an unusable state.
 
-The return value of "failure" in the spec is represented by the string `"failure"`. That is, functions like `parseURL` and `basicURLParse` can return _either_ a URL record _or_ the string `"failure"`.
+The return value of "failure" in the spec is represented by `null`. That is, functions like `parseURL` and `basicURLParse` can return _either_ a URL record _or_ `null`.
+
+## Development instructions
+
+First, install [Node.js](https://nodejs.org/). Then, fetch the dependencies of whatwg-url, by running from this directory:
+
+    npm install
+
+To run tests:
+
+    npm test
+
+To generate a coverage report:
+
+    npm run coverage
+
+To build and run the live viewer:
+
+    npm run build
+    npm run build-live-viewer
+
+Serve the contents of the `live-viewer` directory using any web server.
+
+## Supporting whatwg-url
+
+The jsdom project (including whatwg-url) is a community-driven project maintained by a team of [volunteers](https://github.com/orgs/jsdom/people). You could support us by:
+
+- [Getting professional support for whatwg-url](https://tidelift.com/subscription/pkg/npm-whatwg-url?utm_source=npm-whatwg-url&utm_medium=referral&utm_campaign=readme) as part of a Tidelift subscription. Tidelift helps making open source sustainable for us while giving teams assurances for maintenance, licensing, and security.
+- Contributing directly to the project.

package/lib/URL-impl.js

@@ -1,5 +1,7 @@
 "use strict";
 const usm = require("./url-state-machine");
+const urlencoded = require("./urlencoded");
+const URLSearchParams = require("./URLSearchParams");
 
 exports.implementation = class URLImpl {
   constructor(constructorArgs) {
@@ -9,19 +11,24 @@ exports.implementation = class URLImpl {
     let parsedBase = null;
     if (base !== undefined) {
       parsedBase = usm.basicURLParse(base);
-      if (parsedBase === "failure") {
-        throw new TypeError("Invalid base URL");
+      if (parsedBase === null) {
+        throw new TypeError(`Invalid base URL: ${base}`);
       }
     }
 
     const parsedURL = usm.basicURLParse(url, { baseURL: parsedBase });
-    if (parsedURL === "failure") {
-      throw new TypeError("Invalid URL");
+    if (parsedURL === null) {
+      throw new TypeError(`Invalid URL: ${url}`);
     }
 
+    const query = parsedURL.query !== null ? parsedURL.query : "";
+
     this._url = parsedURL;
 
-    // TODO: query stuff
+    // We cannot invoke the "new URLSearchParams object" algorithm without going through the constructor, which strips
+    // question mark by default. Therefore the doNotStripQMark hack is used.
+    this._query = URLSearchParams.createImpl([query], { doNotStripQMark: true });
+    this._query._url = this;
   }
 
   get href() {
@@ -30,11 +37,17 @@ exports.implementation = class URLImpl {
 
   set href(v) {
     const parsedURL = usm.basicURLParse(v);
-    if (parsedURL === "failure") {
-      throw new TypeError("Invalid URL");
+    if (parsedURL === null) {
+      throw new TypeError(`Invalid URL: ${v}`);
     }
 
     this._url = parsedURL;
+
+    this._query._list.splice(0);
+    const { query } = parsedURL;
+    if (query !== null) {
+      this._query._list = urlencoded.parseUrlencoded(query);
+    }
   }
 
   get origin() {
@@ -161,18 +174,22 @@ exports.implementation = class URLImpl {
   }
 
   set search(v) {
-    // TODO: query stuff
-
     const url = this._url;
 
     if (v === "") {
       url.query = null;
+      this._query._list = [];
       return;
     }
 
     const input = v[0] === "?" ? v.substring(1) : v;
     url.query = "";
     usm.basicURLParse(input, { url, stateOverride: "query" });
+    this._query._list = urlencoded.parseUrlencoded(input);
+  }
+
+  get searchParams() {
+    return this._query;
   }
 
   get hash() {

package/lib/URL.js

@@ -2,195 +2,334 @@
 
 const conversions = require("webidl-conversions");
 const utils = require("./utils.js");
-const Impl = require(".//URL-impl.js");
 
 const impl = utils.implSymbol;
 
-function URL(url) {
-  if (!this || this[impl] || !(this instanceof URL)) {
-    throw new TypeError("Failed to construct 'URL': Please use the 'new' operator, this DOM object constructor cannot be called as a function.");
+class URL {
+  constructor(url) {
+    if (arguments.length < 1) {
+      throw new TypeError("Failed to construct 'URL': 1 argument required, but only " + arguments.length + " present.");
+    }
+    const args = [];
+    {
+      let curArg = arguments[0];
+      curArg = conversions["USVString"](curArg, { context: "Failed to construct 'URL': parameter 1" });
+      args.push(curArg);
+    }
+    {
+      let curArg = arguments[1];
+      if (curArg !== undefined) {
+        curArg = conversions["USVString"](curArg, { context: "Failed to construct 'URL': parameter 2" });
+      }
+      args.push(curArg);
+    }
+    return iface.setup(Object.create(new.target.prototype), args);
   }
-  if (arguments.length < 1) {
-    throw new TypeError("Failed to construct 'URL': 1 argument required, but only " + arguments.length + " present.");
+
+  toJSON() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl].toJSON();
   }
-  const args = [];
-  for (let i = 0; i < arguments.length && i < 2; ++i) {
-    args[i] = arguments[i];
+
+  get href() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["href"];
   }
-  args[0] = conversions["USVString"](args[0]);
-  if (args[1] !== undefined) {
-  args[1] = conversions["USVString"](args[1]);
+
+  set href(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'href' property on 'URL': The provided value" });
+
+    this[impl]["href"] = V;
   }
 
-  module.exports.setup(this, args);
-}
+  toString() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+    return this[impl]["href"];
+  }
+
+  get origin() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
 
-URL.prototype.toJSON = function toJSON() {
-  if (!this || !module.exports.is(this)) {
-    throw new TypeError("Illegal invocation");
+    return this[impl]["origin"];
   }
-  const args = [];
-  for (let i = 0; i < arguments.length && i < 0; ++i) {
-    args[i] = arguments[i];
+
+  get protocol() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["protocol"];
   }
-  return this[impl].toJSON.apply(this[impl], args);
-};
-Object.defineProperty(URL.prototype, "href", {
-  get() {
-    return this[impl].href;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].href = V;
-  },
-  enumerable: true,
-  configurable: true
-});
 
-URL.prototype.toString = function () {
-  if (!this || !module.exports.is(this)) {
-    throw new TypeError("Illegal invocation");
+  set protocol(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'protocol' property on 'URL': The provided value" });
+
+    this[impl]["protocol"] = V;
   }
-  return this.href;
-};
 
-Object.defineProperty(URL.prototype, "origin", {
-  get() {
-    return this[impl].origin;
-  },
-  enumerable: true,
-  configurable: true
-});
+  get username() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
 
-Object.defineProperty(URL.prototype, "protocol", {
-  get() {
-    return this[impl].protocol;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].protocol = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+    return this[impl]["username"];
+  }
 
-Object.defineProperty(URL.prototype, "username", {
-  get() {
-    return this[impl].username;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].username = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+  set username(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
 
-Object.defineProperty(URL.prototype, "password", {
-  get() {
-    return this[impl].password;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].password = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+    V = conversions["USVString"](V, { context: "Failed to set the 'username' property on 'URL': The provided value" });
 
-Object.defineProperty(URL.prototype, "host", {
-  get() {
-    return this[impl].host;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].host = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+    this[impl]["username"] = V;
+  }
 
-Object.defineProperty(URL.prototype, "hostname", {
-  get() {
-    return this[impl].hostname;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].hostname = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+  get password() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
 
-Object.defineProperty(URL.prototype, "port", {
-  get() {
-    return this[impl].port;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].port = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+    return this[impl]["password"];
+  }
 
-Object.defineProperty(URL.prototype, "pathname", {
-  get() {
-    return this[impl].pathname;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].pathname = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+  set password(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
 
-Object.defineProperty(URL.prototype, "search", {
-  get() {
-    return this[impl].search;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].search = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+    V = conversions["USVString"](V, { context: "Failed to set the 'password' property on 'URL': The provided value" });
 
-Object.defineProperty(URL.prototype, "hash", {
-  get() {
-    return this[impl].hash;
-  },
-  set(V) {
-    V = conversions["USVString"](V);
-    this[impl].hash = V;
-  },
-  enumerable: true,
-  configurable: true
-});
+    this[impl]["password"] = V;
+  }
+
+  get host() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["host"];
+  }
+
+  set host(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'host' property on 'URL': The provided value" });
+
+    this[impl]["host"] = V;
+  }
+
+  get hostname() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["hostname"];
+  }
+
+  set hostname(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'hostname' property on 'URL': The provided value" });
+
+    this[impl]["hostname"] = V;
+  }
+
+  get port() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["port"];
+  }
+
+  set port(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'port' property on 'URL': The provided value" });
+
+    this[impl]["port"] = V;
+  }
+
+  get pathname() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["pathname"];
+  }
+
+  set pathname(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'pathname' property on 'URL': The provided value" });
+
+    this[impl]["pathname"] = V;
+  }
 
+  get search() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
 
-module.exports = {
+    return this[impl]["search"];
+  }
+
+  set search(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'search' property on 'URL': The provided value" });
+
+    this[impl]["search"] = V;
+  }
+
+  get searchParams() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return utils.getSameObject(this, "searchParams", () => {
+      return utils.tryWrapperForImpl(this[impl]["searchParams"]);
+    });
+  }
+
+  get hash() {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    return this[impl]["hash"];
+  }
+
+  set hash(V) {
+    if (!this || !module.exports.is(this)) {
+      throw new TypeError("Illegal invocation");
+    }
+
+    V = conversions["USVString"](V, { context: "Failed to set the 'hash' property on 'URL': The provided value" });
+
+    this[impl]["hash"] = V;
+  }
+}
+Object.defineProperties(URL.prototype, {
+  toJSON: { enumerable: true },
+  href: { enumerable: true },
+  toString: { enumerable: true },
+  origin: { enumerable: true },
+  protocol: { enumerable: true },
+  username: { enumerable: true },
+  password: { enumerable: true },
+  host: { enumerable: true },
+  hostname: { enumerable: true },
+  port: { enumerable: true },
+  pathname: { enumerable: true },
+  search: { enumerable: true },
+  searchParams: { enumerable: true },
+  hash: { enumerable: true },
+  [Symbol.toStringTag]: { value: "URL", configurable: true }
+});
+const iface = {
+  // When an interface-module that implements this interface as a mixin is loaded, it will append its own `.is()`
+  // method into this array. It allows objects that directly implements *those* interfaces to be recognized as
+  // implementing this mixin interface.
+  _mixedIntoPredicates: [],
   is(obj) {
-    return !!obj && obj[impl] instanceof Impl.implementation;
+    if (obj) {
+      if (utils.hasOwn(obj, impl) && obj[impl] instanceof Impl.implementation) {
+        return true;
+      }
+      for (const isMixedInto of module.exports._mixedIntoPredicates) {
+        if (isMixedInto(obj)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  },
+  isImpl(obj) {
+    if (obj) {
+      if (obj instanceof Impl.implementation) {
+        return true;
+      }
+
+      const wrapper = utils.wrapperForImpl(obj);
+      for (const isMixedInto of module.exports._mixedIntoPredicates) {
+        if (isMixedInto(wrapper)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  },
+  convert(obj, { context = "The provided value" } = {}) {
+    if (module.exports.is(obj)) {
+      return utils.implForWrapper(obj);
+    }
+    throw new TypeError(`${context} is not of type 'URL'.`);
   },
+
   create(constructorArgs, privateData) {
     let obj = Object.create(URL.prototype);
-    this.setup(obj, constructorArgs, privateData);
+    obj = this.setup(obj, constructorArgs, privateData);
     return obj;
   },
+  createImpl(constructorArgs, privateData) {
+    let obj = Object.create(URL.prototype);
+    obj = this.setup(obj, constructorArgs, privateData);
+    return utils.implForWrapper(obj);
+  },
+  _internalSetup(obj) {},
   setup(obj, constructorArgs, privateData) {
     if (!privateData) privateData = {};
+
     privateData.wrapper = obj;
 
-    obj[impl] = new Impl.implementation(constructorArgs, privateData);
+    this._internalSetup(obj);
+    Object.defineProperty(obj, impl, {
+      value: new Impl.implementation(constructorArgs, privateData),
+      configurable: true
+    });
+
     obj[impl][utils.wrapperSymbol] = obj;
+    if (Impl.init) {
+      Impl.init(obj[impl], privateData);
+    }
+    return obj;
   },
   interface: URL,
   expose: {
-    Window: { URL: URL },
-    Worker: { URL: URL }
+    Window: { URL },
+    Worker: { URL }
   }
-};
+}; // iface
+module.exports = iface;
 
+const Impl = require("./URL-impl.js");