diff --git a/doc/api/url.md b/doc/api/url.md index 50e7433e6110e5..435bbff9d7a163 100755 --- a/doc/api/url.md +++ b/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 diff --git a/lib/internal/url.js b/lib/internal/url.js index 84e04ee9d8fa85..27f6e56861b9fc 100644 --- a/lib/internal/url.js +++ b/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> + // 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 + 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); diff --git a/test/parallel/test-whatwg-url-searchparams-constructor.js b/test/parallel/test-whatwg-url-searchparams-constructor.js index 9b7ca1e4e9c54a..cb6ee0c9c04550 100644 --- a/test/parallel/test-whatwg-url-searchparams-constructor.js +++ b/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$/); diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index 0ac15a14b93341..40dd2fa137f11e 100644 --- a/tools/doc/type-parser.js +++ b/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' };