Skip to content

Commit c505b81

Browse files
committed
doc: document URLSearchParams constructor
PR-URL: #11060 Ref: whatwg/url#175 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>
1 parent 29f7587 commit c505b81

File tree

1 file changed

+122
-4
lines changed

1 file changed

+122
-4
lines changed

doc/api/url.md

+122-4
Original file line numberDiff line numberDiff line change
@@ -525,10 +525,12 @@ value returned is equivalent to that of `url.href`.
525525
### Class: URLSearchParams
526526

527527
The `URLSearchParams` object provides read and write access to the query of a
528-
`URL`.
528+
`URL`. The `URLSearchParams` class can also be used standalone with one of the
529+
four following constructors.
529530

530531
```js
531-
const URL = require('url').URL;
532+
const { URL, URLSearchParams } = require('url');
533+
532534
const myURL = new URL('https://example.org/?abc=123');
533535
console.log(myURL.searchParams.get('abc'));
534536
// Prints 123
@@ -541,11 +543,125 @@ myURL.searchParams.delete('abc');
541543
myURL.searchParams.set('a', 'b');
542544
console.log(myURL.href);
543545
// Prints https://example.org/?a=b
546+
547+
const newSearchParams = new URLSearchParams(myURL.searchParams);
548+
// The above is equivalent to
549+
// const newSearchParams = new URLSearchParams(myURL.search);
550+
551+
newSearchParams.append('a', 'c');
552+
console.log(myURL.href);
553+
// Prints https://example.org/?a=b
554+
console.log(newSearchParams.toString());
555+
// Prints a=b&a=c
556+
557+
// newSearchParams.toString() is implicitly called
558+
myURL.search = newSearchParams;
559+
console.log(myURL.href);
560+
// Prints https://example.org/?a=b&a=c
561+
newSearchParams.delete('a');
562+
console.log(myURL.href);
563+
// Prints https://example.org/?a=b&a=c
564+
```
565+
566+
#### Constructor: new URLSearchParams()
567+
568+
Instantiate a new empty `URLSearchParams` object.
569+
570+
#### Constructor: new URLSearchParams(string)
571+
572+
* `string` {String} A query string
573+
574+
Parse the `string` as a query string, and use it to instantiate a new
575+
`URLSearchParams` object. A leading `'?'`, if present, is ignored.
576+
577+
```js
578+
const { URLSearchParams } = require('url');
579+
let params;
580+
581+
params = new URLSearchParams('user=abc&query=xyz');
582+
console.log(params.get('user'));
583+
// Prints 'abc'
584+
console.log(params.toString());
585+
// Prints 'user=abc&query=xyz'
586+
587+
params = new URLSearchParams('?user=abc&query=xyz');
588+
console.log(params.toString());
589+
// Prints 'user=abc&query=xyz'
544590
```
545591

546-
#### Constructor: new URLSearchParams([init])
592+
#### Constructor: new URLSearchParams(obj)
593+
594+
* `obj` {Object} An object representing a collection of key-value pairs
595+
596+
Instantiate a new `URLSearchParams` object with a query hash map. The key and
597+
value of each property of `obj` are always coerced to strings.
547598

548-
* `init` {String} The URL query
599+
*Note*: Unlike [`querystring`][] module, duplicate keys in the form of array
600+
values are not allowed. Arrays are stringified using [`array.toString()`][],
601+
which simply joins all array elements with commas.
602+
603+
```js
604+
const { URLSearchParams } = require('url');
605+
const params = new URLSearchParams({
606+
user: 'abc',
607+
query: ['first', 'second']
608+
});
609+
console.log(params.getAll('query'));
610+
// Prints ['first,second']
611+
console.log(params.toString());
612+
// Prints 'user=abc&query=first%2Csecond'
613+
```
614+
615+
#### Constructor: new URLSearchParams(iterable)
616+
617+
* `iterable` {Iterable} An iterable object whose elements are key-value pairs
618+
619+
Instantiate a new `URLSearchParams` object with an iterable map in a way that
620+
is similar to [`Map`][]'s constructor. `iterable` can be an Array or any
621+
iterable object. That means `iterable` can be another `URLSearchParams`, in
622+
which case the constructor will simply create a clone of the provided
623+
`URLSearchParams`. Elements of `iterable` are key-value pairs, and can
624+
themselves be any iterable object.
625+
626+
Duplicate keys are allowed.
627+
628+
```js
629+
const { URLSearchParams } = require('url');
630+
let params;
631+
632+
// Using an array
633+
params = new URLSearchParams([
634+
['user', 'abc'],
635+
['query', 'first'],
636+
['query', 'second']
637+
]);
638+
console.log(params.toString());
639+
// Prints 'user=abc&query=first&query=second'
640+
641+
// Using a Map object
642+
const map = new Map();
643+
map.set('user', 'abc');
644+
map.set('query', 'xyz');
645+
params = new URLSearchParams(map);
646+
console.log(params.toString());
647+
// Prints 'user=abc&query=xyz'
648+
649+
// Using a generator function
650+
function* getQueryPairs() {
651+
yield ['user', 'abc'];
652+
yield ['query', 'first'];
653+
yield ['query', 'second'];
654+
}
655+
params = new URLSearchParams(getQueryPairs());
656+
console.log(params.toString());
657+
// Prints 'user=abc&query=first&query=second'
658+
659+
// Each key-value pair must have exactly two elements
660+
new URLSearchParams([
661+
['user', 'abc', 'error']
662+
]);
663+
// Throws TypeError: Each query pair must be a name/value tuple
664+
```
549665

550666
#### urlSearchParams.append(name, value)
551667

@@ -712,3 +828,5 @@ console.log(myURL.origin);
712828
[`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
713829
[`url.format()`]: #url_url_format_urlobject
714830
[Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
831+
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
832+
[`array.toString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString

0 commit comments

Comments
 (0)