url: extend URLSearchParams constructor

doc/api/url.md

@@ -525,10 +525,12 @@ value returned is equivalent to that of `url.href`.
 ### Class: URLSearchParams
 
 The `URLSearchParams` object provides read and write access to the query of a
-`URL`.
+`URL`. The `URLSearchParams` class can also be used standalone with one of the
+four following constructors.
 
 ```js
-const URL = require('url').URL;
+const { URL, URLSearchParams } = require('url');
+
 const myURL = new URL('https://example.org/?abc=123');
 console.log(myURL.searchParams.get('abc'));
   // Prints 123
@@ -541,11 +543,125 @@ myURL.searchParams.delete('abc');
 myURL.searchParams.set('a', 'b');
 console.log(myURL.href);
   // Prints https://example.org/?a=b
+
+const newSearchParams = new URLSearchParams(myURL.searchParams);
+// The above is equivalent to
+// const newSearchParams = new URLSearchParams(myURL.search);
+
+newSearchParams.append('a', 'c');
+console.log(myURL.href);
+  // Prints https://example.org/?a=b
+console.log(newSearchParams.toString());
+  // Prints a=b&a=c
+
+// newSearchParams.toString() is implicitly called
+myURL.search = newSearchParams;
+console.log(myURL.href);
+  // Prints https://example.org/?a=b&a=c
+newSearchParams.delete('a');
+console.log(myURL.href);
+  // Prints https://example.org/?a=b&a=c
+```
+
+#### Constructor: new URLSearchParams()
+
+Instantiate a new empty `URLSearchParams` object.
+
+#### Constructor: new URLSearchParams(string)
+
+* `string` {String} A query string
+
+Parse the `string` as a query string, and use it to instantiate a new
+`URLSearchParams` object. A leading `'?'`, if present, is ignored.
+
+```js
+const { URLSearchParams } = require('url');
+let params;
+
+params = new URLSearchParams('user=abc&query=xyz');
+console.log(params.get('user'));
+  // Prints 'abc'
+console.log(params.toString());
+  // Prints 'user=abc&query=xyz'
+
+params = new URLSearchParams('?user=abc&query=xyz');
+console.log(params.toString());
+  // Prints 'user=abc&query=xyz'
 ```
 
-#### Constructor: new URLSearchParams([init])
+#### Constructor: new URLSearchParams(obj)
+
+* `obj` {Object} An object representing a collection of key-value pairs
+
+Instantiate a new `URLSearchParams` object with a query hash map. The key and
+value of each property of `obj` are always coerced to strings.
 
-* `init` {String} The URL query
+*Note*: Unlike [`querystring`][] module, duplicate keys in the form of array
+values are not allowed. Arrays are stringified using [`array.toString()`][],
+which simply joins all array elements with commas.
+
+```js
+const { URLSearchParams } = require('url');
+const params = new URLSearchParams({
+  user: 'abc',
+  query: ['first', 'second']
+});
+console.log(params.getAll('query'));
+  // Prints ['first,second']
+console.log(params.toString());
+  // Prints 'user=abc&query=first%2Csecond'
+```
+
+#### Constructor: new URLSearchParams(iterable)
+
+* `iterable` {Iterable} An iterable object whose elements are key-value pairs
+
+Instantiate a new `URLSearchParams` object with an iterable map in a way that
+is similar to [`Map`][]'s constructor. `iterable` can be an Array or any
+iterable object. That means `iterable` can be another `URLSearchParams`, in
+which case the constructor will simply create a clone of the provided
+`URLSearchParams`.  Elements of `iterable` are key-value pairs, and can
+themselves be any iterable object.
+
+Duplicate keys are allowed.
+
+```js
+const { URLSearchParams } = require('url');
+let params;
+
+// Using an array
+params = new URLSearchParams([
+  ['user', 'abc'],
+  ['query', 'first'],
+  ['query', 'second']
+]);
+console.log(params.toString());
+  // Prints 'user=abc&query=first&query=second'
+
+// Using a Map object
+const map = new Map();
+map.set('user', 'abc');
+map.set('query', 'xyz');
+params = new URLSearchParams(map);
+console.log(params.toString());
+  // Prints 'user=abc&query=xyz'
+
+// Using a generator function
+function* getQueryPairs() {
+  yield ['user', 'abc'];
+  yield ['query', 'first'];
+  yield ['query', 'second'];
+}
+params = new URLSearchParams(getQueryPairs());
+console.log(params.toString());
+  // Prints 'user=abc&query=first&query=second'
+
+// Each key-value pair must have exactly two elements
+new URLSearchParams([
+  ['user', 'abc', 'error']
+]);
+  // Throws TypeError: Each query pair must be a name/value tuple
+```
 
 #### urlSearchParams.append(name, value)
 
@@ -712,3 +828,5 @@ console.log(myURL.origin);
 [`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
 [`url.format()`]: #url_url_format_urlobject
 [Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
+[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
+[`array.toString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString

lib/internal/url.js

@@ -648,11 +648,53 @@ function getObjectFromParams(array) {
 }
 
 class URLSearchParams {
-  constructor(init = '') {
-    if (init instanceof URLSearchParams) {
-      const childParams = init[searchParams];
-      this[searchParams] = childParams.slice();
+  // URL Standard says the default value is '', but as undefined and '' have
+  // the same result, undefined is used to prevent unnecessary parsing.
+  // Default parameter is necessary to keep URLSearchParams.length === 0 in
+  // accordance with Web IDL spec.
+  constructor(init = undefined) {
+    if (init === null || init === undefined) {
+      this[searchParams] = [];
+    } else if (typeof init === 'object') {
+      const method = init[Symbol.iterator];
+      if (method === this[Symbol.iterator]) {
+        // While the spec does not have this branch, we can use it as a
+        // shortcut to avoid having to go through the costly generic iterator.
+        const childParams = init[searchParams];
+        this[searchParams] = childParams.slice();
+      } else if (method !== null && method !== undefined) {
+        if (typeof method !== 'function') {
+          throw new TypeError('Query pairs must be iterable');
+        }
+
+        // sequence<sequence<USVString>>
+        // Note: per spec we have to first exhaust the lists then process them
+        const pairs = [];
+        for (const pair of init) {
+          if (typeof pair !== 'object' ||
+              typeof pair[Symbol.iterator] !== 'function') {
+            throw new TypeError('Each query pair must be iterable');
+          }
+          pairs.push(Array.from(pair));
+        }
+
+        this[searchParams] = [];
+        for (const pair of pairs) {
+          if (pair.length !== 2) {
+            throw new TypeError('Each query pair must be a name/value tuple');
+          }
+          this[searchParams].push(String(pair[0]), String(pair[1]));
+        }
+      } else {
+        // record<USVString, USVString>
+        this[searchParams] = [];
+        for (const key of Object.keys(init)) {
+          const value = String(init[key]);
+          this[searchParams].push(key, value);
+        }
+      }
     } else {
+      // USVString
       init = String(init);
       if (init[0] === '?') init = init.slice(1);
       initSearchParams(this, init);

test/parallel/test-whatwg-url-searchparams-constructor.js

@@ -16,23 +16,30 @@ assert.strictEqual(params + '', 'a=b');
 params = new URLSearchParams(params);
 assert.strictEqual(params + '', 'a=b');
 
-// URLSearchParams constructor, empty.
+// URLSearchParams constructor, no arguments
+params = new URLSearchParams();
+assert.strictEqual(params.toString(), '');
+
 assert.throws(() => URLSearchParams(), TypeError,
               'Calling \'URLSearchParams\' without \'new\' should throw.');
-// assert.throws(() => new URLSearchParams(DOMException.prototype), TypeError);
-assert.throws(() => {
-  new URLSearchParams({
-    toString() { throw new TypeError('Illegal invocation'); }
-  });
-}, TypeError);
+
+// URLSearchParams constructor, undefined and null as argument
+params = new URLSearchParams(undefined);
+assert.strictEqual(params.toString(), '');
+params = new URLSearchParams(null);
+assert.strictEqual(params.toString(), '');
+
+// URLSearchParams constructor, empty string as argument
 params = new URLSearchParams('');
-assert.notStrictEqual(params, null, 'constructor returned non-null value.');
+// eslint-disable-next-line no-restricted-properties
+assert.notEqual(params, null, 'constructor returned non-null value.');
 // eslint-disable-next-line no-proto
 assert.strictEqual(params.__proto__, URLSearchParams.prototype,
                    'expected URLSearchParams.prototype as prototype.');
+
+// URLSearchParams constructor, {} as argument
 params = new URLSearchParams({});
-// assert.strictEqual(params + '', '%5Bobject+Object%5D=');
-assert.strictEqual(params + '', '%5Bobject%20Object%5D=');
+assert.strictEqual(params + '', '');
 
 // URLSearchParams constructor, string.
 params = new URLSearchParams('a=b');
@@ -128,3 +135,56 @@ params = new URLSearchParams('a=b%f0%9f%92%a9c');
 assert.strictEqual(params.get('a'), 'b\uD83D\uDCA9c');
 params = new URLSearchParams('a%f0%9f%92%a9b=c');
 assert.strictEqual(params.get('a\uD83D\uDCA9b'), 'c');
+
+// Constructor with sequence of sequences of strings
+params = new URLSearchParams([]);
+// eslint-disable-next-line no-restricted-properties
+assert.notEqual(params, null, 'constructor returned non-null value.');
+params = new URLSearchParams([['a', 'b'], ['c', 'd']]);
+assert.strictEqual(params.get('a'), 'b');
+assert.strictEqual(params.get('c'), 'd');
+assert.throws(() => new URLSearchParams([[1]]),
+              /^TypeError: Each query pair must be a name\/value tuple$/);
+assert.throws(() => new URLSearchParams([[1, 2, 3]]),
+              /^TypeError: Each query pair must be a name\/value tuple$/);
+
+[
+  // Further confirmation needed
+  // https://github.com/w3c/web-platform-tests/pull/4523#discussion_r98337513
+  // {
+  //   input: {'+': '%C2'},
+  //   output: [[' ', '\uFFFD']],
+  //   name: 'object with +'
+  // },
+  {
+    input: {c: 'x', a: '?'},
+    output: [['c', 'x'], ['a', '?']],
+    name: 'object with two keys'
+  },
+  {
+    input: [['c', 'x'], ['a', '?']],
+    output: [['c', 'x'], ['a', '?']],
+    name: 'array with two keys'
+  }
+].forEach((val) => {
+  const params = new URLSearchParams(val.input);
+  assert.deepStrictEqual(Array.from(params), val.output,
+                         `Construct with ${val.name}`);
+});
+
+// Custom [Symbol.iterator]
+params = new URLSearchParams();
+params[Symbol.iterator] = function *() {
+  yield ['a', 'b'];
+};
+const params2 = new URLSearchParams(params);
+assert.strictEqual(params2.get('a'), 'b');
+
+assert.throws(() => new URLSearchParams({ [Symbol.iterator]: 42 }),
+              /^TypeError: Query pairs must be iterable$/);
+assert.throws(() => new URLSearchParams([{}]),
+              /^TypeError: Each query pair must be iterable$/);
+assert.throws(() => new URLSearchParams(['a']),
+              /^TypeError: Each query pair must be iterable$/);
+assert.throws(() => new URLSearchParams([{ [Symbol.iterator]: 42 }]),
+              /^TypeError: Each query pair must be iterable$/);

tools/doc/type-parser.js

@@ -36,6 +36,8 @@ const typeMap = {
   'http.IncomingMessage': 'http.html#http_class_http_incomingmessage',
   'http.Server': 'http.html#http_class_http_server',
   'http.ServerResponse': 'http.html#http_class_http_serverresponse',
+  'Iterable': jsDocPrefix +
+              'Reference/Iteration_protocols#The_iterable_protocol',
   'Iterator': jsDocPrefix +
               'Reference/Iteration_protocols#The_iterator_protocol'
 };