url: add URLPattern implementation · nodejs/node@bc97a90
@@ -714,6 +714,129 @@ Parses a string as a URL. If `base` is provided, it will be used as the base
714714URL for the purpose of resolving non-absolute `input` URLs. Returns `null`
715715if `input` is not a valid.
716716717+### Class: `URLPattern`
718+719+> Stability: 1 - Experimental
720+721+<!-- YAML
722+added: REPLACEME
723+-->
724+725+The `URLPattern` API provides an interface to match URLs or parts of URLs
726+against a pattern.
727+728+```js
729+const myPattern = new URLPattern('https://nodejs.org/docs/latest/api/*.html');
730+console.log(myPattern.exec('https://nodejs.org/docs/latest/api/dns.html'));
731+// Prints:
732+// {
733+// "hash": { "groups": { "0": "" }, "input": "" },
734+// "hostname": { "groups": {}, "input": "nodejs.org" },
735+// "inputs": [
736+// "https://nodejs.org/docs/latest/api/dns.html"
737+// ],
738+// "password": { "groups": { "0": "" }, "input": "" },
739+// "pathname": { "groups": { "0": "dns" }, "input": "/docs/latest/api/dns.html" },
740+// "port": { "groups": {}, "input": "" },
741+// "protocol": { "groups": {}, "input": "https" },
742+// "search": { "groups": { "0": "" }, "input": "" },
743+// "username": { "groups": { "0": "" }, "input": "" }
744+// }
745+746+console.log(myPattern.test('https://nodejs.org/docs/latest/api/dns.html'));
747+// Prints: true
748+```
749+750+#### `new URLPattern()`
751+752+Instantiate a new empty `URLPattern` object.
753+754+#### `new URLPattern(string[, baseURL][, options])`
755+756+* `string` {string} A URL string
757+* `baseURL` {string | undefined} A base URL string
758+* `options` {Object} Options
759+760+Parse the `string` as a URL, and use it to instantiate a new
761+`URLPattern` object.
762+763+If `baseURL` is not specified, it defaults to `undefined`.
764+765+An option can have `ignoreCase` boolean attribute which enables
766+case-insensitive matching if set to true.
767+768+The constructor can throw a `TypeError` to indicate parsing failure.
769+770+#### `new URLPattern(objg[, baseURL][, options])`
771+772+* `obj` {Object} An input pattern
773+* `baseURL` {string | undefined} A base URL string
774+* `options` {Object} Options
775+776+Parse the `Object` as an input pattern, and use it to instantiate a new
777+`URLPattern` object. The object members can be any of `protocol`, `username`,
778+`password`, `hostname`, `port`, `pathname`, `search`, `hash` or `baseURL`.
779+780+If `baseURL` is not specified, it defaults to `undefined`.
781+782+An option can have `ignoreCase` boolean attribute which enables
783+case-insensitive matching if set to true.
784+785+The constructor can throw a `TypeError` to indicate parsing failure.
786+787+#### `urlPattern.exec(input[, baseURL])`
788+789+* `input` {string | Object} A URL or URL parts
790+* `baseURL` {string | undefined} A base URL string
791+792+Input can be a string or an object providing the individual URL parts. The
793+object members can be any of `protocol`, `username`, `password`, `hostname`,
794+`port`, `pathname`, `search`, `hash` or `baseURL`.
795+796+If `baseURL` is not specified, it will default to `undefined`.
797+798+Returns an object with an `inputs` key containing the array of arguments
799+passed into the function and keys of the URL components which contains the
800+matched input and matched groups.
801+802+```js
803+const myPattern = new URLPattern('https://nodejs.org/docs/latest/api/*.html');
804+console.log(myPattern.exec('https://nodejs.org/docs/latest/api/dns.html'));
805+// Prints:
806+// {
807+// "hash": { "groups": { "0": "" }, "input": "" },
808+// "hostname": { "groups": {}, "input": "nodejs.org" },
809+// "inputs": [
810+// "https://nodejs.org/docs/latest/api/dns.html"
811+// ],
812+// "password": { "groups": { "0": "" }, "input": "" },
813+// "pathname": { "groups": { "0": "dns" }, "input": "/docs/latest/api/dns.html" },
814+// "port": { "groups": {}, "input": "" },
815+// "protocol": { "groups": {}, "input": "https" },
816+// "search": { "groups": { "0": "" }, "input": "" },
817+// "username": { "groups": { "0": "" }, "input": "" }
818+// }
819+```
820+821+#### `urlPattern.test(input[, baseURL])`
822+823+* `input` {string | Object} A URL or URL parts
824+* `baseURL` {string | undefined} A base URL string
825+826+Input can be a string or an object providing the individual URL parts. The
827+object members can be any of `protocol`, `username`, `password`, `hostname`,
828+`port`, `pathname`, `search`, `hash` or `baseURL`.
829+830+If `baseURL` is not specified, it will default to `undefined`.
831+832+Returns a boolean indicating if the input matches the current pattern.
833+834+```js
835+const myPattern = new URLPattern('https://nodejs.org/docs/latest/api/*.html');
836+console.log(myPattern.test('https://nodejs.org/docs/latest/api/dns.html'));
837+// Prints: true
838+```
839+717840### Class: `URLSearchParams`
718841719842<!-- YAML