diff --git a/XXX-url.md b/XXX-url.md new file mode 100644 index 0000000..b04f44d --- /dev/null +++ b/XXX-url.md @@ -0,0 +1,170 @@ +| Title | Implement WHATWG URL Spec | +|--------|-----------------------------| +| Author | @jasnell | +| Status | DRAFT | +| Date | 2016-06-30T09:00:00-07:00 | + +## Description + +The WHATWG URL Standard specifies updated syntax, parsing and serialization of +URLs as currently implemented by the main Web Browsers. The existing Node.js +`url` module parsing and serialization implementation currently does not support +the URL standard and fails to pass 160 of the WHATWG URL parsing tests. + +This proposal is to implement the WHATWG URL Standard by modifying the existing +`url` module to provide an implementation of the `URL` object and associated +APIs. Doing so improves the robustness of URL parsing, provides consistency +with browser js code, and can eventually allow the reduction of node.js specific +APIs. + +Initially, the implementation would be introduced as an undocumented +experimental feature exposed via a new `URL` property in the `url` module. + +Because the existing `require('url')` module remains, there should be no +backwards compatibility concerns. Once a decision is made to provide official, +documented support for the new URL implementation, a decision would be made +about whether to switch the internal uses of `require('url').parse()` to the +new `URL` implementation. + +The current implementation can be found at: + +https://github.com/nodejs/node/pull/7448 + +## Example + +```js +const URL = require('url').URL; +const url = new URL('http://user:pass@example.org:1234/p/a/t/h?xyz=abc#hash'); + +console.log(url.protocol); // http: +console.log(url.username); // user +console.log(url.password); // password +console.log(url.host); // example.org:1234 +console.log(url.hostname); // example.org +console.log(url.port); // 1234 +console.log(url.pathname); // /p/a/t/h +console.log(url.search); // ?xyz=abc +console.log(url.searchParams); // SearchParams object +console.log(url.hash); // hash + +// The SearchParams object is defined by the WHATWG spec also +url.searchParams.append('key', 'value'); + +console.log(url); + // http://user:pass@example.org:1234/p/a/t/h?xyz=abc&key=value#hash + + +// Example using a base URL +const url2 = new URL('/foo', url); +console.log(url.protocol); // http: +console.log(url.username); // user +console.log(url.password); // password +console.log(url.host); // example.org:1234 +console.log(url.hostname); // example.org +console.log(url.port); // 1234 +console.log(url.pathname); // /foo +console.log(url.search); // '' +console.log(url.searchParams); // SearchParams object +console.log(url.hash); // '' +``` + +## APIs + +The public API would be as defined by the +[WHATWG spec](https://url.spec.whatwg.org/#api). + +### `new URL(href, base)` + +The constructor implements the WHATWG basic parsing algorithm. Accessible via +`const URL = require('url').URL` + +* `href` is a `string` containing the URL to parse. +* `base` is either a `string` or a `URL` that contains the base URL to resolve + against while parsing. + +See https://url.spec.whatwg.org/#urlutils-members for detail on the properties +of the `URL` object. + +#### `url.protocol` + +* Returns a string +* Getter/Setter + +#### `url.username` + +* Returns a string +* Getter/Setter + +#### `url.password` + +* Returns a string +* Getter/Setter + +#### `url.host` + +* Returns a string +* Getter/Setter + +#### `url.hostname` + +* Returns a string +* Getter/Setter + +#### `url.port` + +* Returns an integer +* Getter/Setter + +#### `url.pathname` + +* Returns a string +* Getter/Setter + +#### `url.search` + +* Returns a string +* Getter/Setter + +#### `url.searchParams` + +* Returns a URLSearchParams object +* Getter + +#### `url.hash` + +* Returns a string +* Getter/Setter + +#### `url.origin` + +* Returns a string +* Getter + +#### `url.href` + +* Returns a string +* Getter + +#### `url.toString()` + +* Returns a string (same as `url.href`) + +### `URLSearchParams` + +Returned by the `url.searchParams` property and provides access read and write +access to the search params. It is defined at +https://url.spec.whatwg.org/#interface-urlsearchparams. + +Accessible via `require('url').URLSearchParams` + +#### `searchParams.append(name, value)` +#### `searchParams.delete(name)` +#### `searchParams.get(name)` +#### `searchParams.getAll(name)` +#### `searchParams.has(name)` +#### `searchParams.set(name, value)` +#### `searchParams.*[Symbol.iterator]()` +#### `searchParams.toString()` + +### `URL.domainToASCII(domain)` +### `URL.domainToUnicode(domain)`