@@ -525,10 +525,12 @@ value returned is equivalent to that of `url.href`.
525
525
### Class: URLSearchParams
526
526
527
527
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.
529
530
530
531
``` js
531
- const URL = require (' url' ).URL ;
532
+ const { URL , URLSearchParams } = require (' url' );
533
+
532
534
const myURL = new URL (' https://example.org/?abc=123' );
533
535
console .log (myURL .searchParams .get (' abc' ));
534
536
// Prints 123
@@ -541,11 +543,125 @@ myURL.searchParams.delete('abc');
541
543
myURL .searchParams .set (' a' , ' b' );
542
544
console .log (myURL .href );
543
545
// 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'
544
590
```
545
591
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.
547
598
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
+ ```
549
665
550
666
#### urlSearchParams.append(name, value)
551
667
@@ -712,3 +828,5 @@ console.log(myURL.origin);
712
828
[ `url.parse()` ] : #url_url_parse_urlstring_parsequerystring_slashesdenotehost
713
829
[ `url.format()` ] : #url_url_format_urlobject
714
830
[ 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