url.d.ts (37574B)
1 /** 2 * The `url` module provides utilities for URL resolution and parsing. It can be 3 * accessed using: 4 * 5 * ```js 6 * import url from 'url'; 7 * ``` 8 * @see [source](https://github.com/nodejs/node/blob/v16.20.2/lib/url.js) 9 */ 10 declare module "url" { 11 import { Blob } from "node:buffer"; 12 import { ClientRequestArgs } from "node:http"; 13 import { ParsedUrlQuery, ParsedUrlQueryInput } from "node:querystring"; 14 // Input to `url.format` 15 interface UrlObject { 16 auth?: string | null | undefined; 17 hash?: string | null | undefined; 18 host?: string | null | undefined; 19 hostname?: string | null | undefined; 20 href?: string | null | undefined; 21 pathname?: string | null | undefined; 22 protocol?: string | null | undefined; 23 search?: string | null | undefined; 24 slashes?: boolean | null | undefined; 25 port?: string | number | null | undefined; 26 query?: string | null | ParsedUrlQueryInput | undefined; 27 } 28 // Output of `url.parse` 29 interface Url { 30 auth: string | null; 31 hash: string | null; 32 host: string | null; 33 hostname: string | null; 34 href: string; 35 path: string | null; 36 pathname: string | null; 37 protocol: string | null; 38 search: string | null; 39 slashes: boolean | null; 40 port: string | null; 41 query: string | null | ParsedUrlQuery; 42 } 43 interface UrlWithParsedQuery extends Url { 44 query: ParsedUrlQuery; 45 } 46 interface UrlWithStringQuery extends Url { 47 query: string | null; 48 } 49 /** 50 * The `url.parse()` method takes a URL string, parses it, and returns a URL 51 * object. 52 * 53 * A `TypeError` is thrown if `urlString` is not a string. 54 * 55 * A `URIError` is thrown if the `auth` property is present but cannot be decoded. 56 * 57 * Use of the legacy `url.parse()` method is discouraged. Users should 58 * use the WHATWG `URL` API. Because the `url.parse()` method uses a 59 * lenient, non-standard algorithm for parsing URL strings, security 60 * issues can be introduced. Specifically, issues with [host name spoofing](https://hackerone.com/reports/678487) and 61 * incorrect handling of usernames and passwords have been identified. 62 * 63 * Deprecation of this API has been shelved for now primarily due to the the 64 * inability of the [WHATWG API to parse relative URLs](https://github.com/nodejs/node/issues/12682#issuecomment-1154492373). 65 * [Discussions are ongoing](https://github.com/whatwg/url/issues/531) for the best way to resolve this. 66 * 67 * @since v0.1.25 68 * @param urlString The URL string to parse. 69 * @param [parseQueryString=false] If `true`, the `query` property will always be set to an object returned by the {@link querystring} module's `parse()` method. If `false`, the `query` property 70 * on the returned URL object will be an unparsed, undecoded string. 71 * @param [slashesDenoteHost=false] If `true`, the first token after the literal string `//` and preceding the next `/` will be interpreted as the `host`. For instance, given `//foo/bar`, the 72 * result would be `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`. 73 */ 74 function parse(urlString: string): UrlWithStringQuery; 75 function parse( 76 urlString: string, 77 parseQueryString: false | undefined, 78 slashesDenoteHost?: boolean, 79 ): UrlWithStringQuery; 80 function parse(urlString: string, parseQueryString: true, slashesDenoteHost?: boolean): UrlWithParsedQuery; 81 function parse(urlString: string, parseQueryString: boolean, slashesDenoteHost?: boolean): Url; 82 /** 83 * The URL object has both a `toString()` method and `href` property that return string serializations of the URL. 84 * These are not, however, customizable in any way. The `url.format(URL[, options])` method allows for basic 85 * customization of the output. 86 * Returns a customizable serialization of a URL `String` representation of a `WHATWG URL` object. 87 * 88 * ```js 89 * import url from 'url'; 90 * const myURL = new URL('https://a:b@測試?abc#foo'); 91 * 92 * console.log(myURL.href); 93 * // Prints https://a:b@xn--g6w251d/?abc#foo 94 * 95 * console.log(myURL.toString()); 96 * // Prints https://a:b@xn--g6w251d/?abc#foo 97 * 98 * console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); 99 * // Prints 'https://測試/?abc' 100 * ``` 101 * @since v7.6.0 102 * @param urlObject A `WHATWG URL` object 103 * @param options 104 */ 105 function format(urlObject: URL, options?: URLFormatOptions): string; 106 /** 107 * The `url.format()` method returns a formatted URL string derived from `urlObject`. 108 * 109 * ```js 110 * import url from 'node:url'; 111 * url.format({ 112 * protocol: 'https', 113 * hostname: 'example.com', 114 * pathname: '/some/path', 115 * query: { 116 * page: 1, 117 * format: 'json', 118 * }, 119 * }); 120 * 121 * // => 'https://example.com/some/path?page=1&format=json' 122 * ``` 123 * 124 * If `urlObject` is not an object or a string, `url.format()` will throw a `TypeError`. 125 * 126 * The formatting process operates as follows: 127 * 128 * * A new empty string `result` is created. 129 * * If `urlObject.protocol` is a string, it is appended as-is to `result`. 130 * * Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an `Error` is thrown. 131 * * For all string values of `urlObject.protocol` that _do not end_ with an ASCII 132 * colon (`:`) character, the literal string `:` will be appended to `result`. 133 * * If either of the following conditions is true, then the literal string `//` will be appended to `result`: 134 * * `urlObject.slashes` property is true; 135 * * `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or `file`; 136 * * If the value of the `urlObject.auth` property is truthy, and either `urlObject.host` or `urlObject.hostname` are not `undefined`, the value of `urlObject.auth` will be coerced into a string 137 * and appended to `result` followed by the literal string `@`. 138 * * If the `urlObject.host` property is `undefined` then: 139 * * If the `urlObject.hostname` is a string, it is appended to `result`. 140 * * Otherwise, if `urlObject.hostname` is not `undefined` and is not a string, 141 * an `Error` is thrown. 142 * * If the `urlObject.port` property value is truthy, and `urlObject.hostname` is not `undefined`: 143 * * The literal string `:` is appended to `result`, and 144 * * The value of `urlObject.port` is coerced to a string and appended to `result`. 145 * * Otherwise, if the `urlObject.host` property value is truthy, the value of `urlObject.host` is coerced to a string and appended to `result`. 146 * * If the `urlObject.pathname` property is a string that is not an empty string: 147 * * If the `urlObject.pathname` _does not start_ with an ASCII forward slash 148 * (`/`), then the literal string `'/'` is appended to `result`. 149 * * The value of `urlObject.pathname` is appended to `result`. 150 * * Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an `Error` is thrown. 151 * * If the `urlObject.search` property is `undefined` and if the `urlObject.query`property is an `Object`, the literal string `?` is appended to `result` followed by the output of calling the 152 * `querystring` module's `stringify()` method passing the value of `urlObject.query`. 153 * * Otherwise, if `urlObject.search` is a string: 154 * * If the value of `urlObject.search` _does not start_ with the ASCII question 155 * mark (`?`) character, the literal string `?` is appended to `result`. 156 * * The value of `urlObject.search` is appended to `result`. 157 * * Otherwise, if `urlObject.search` is not `undefined` and is not a string, an `Error` is thrown. 158 * * If the `urlObject.hash` property is a string: 159 * * If the value of `urlObject.hash` _does not start_ with the ASCII hash (`#`) 160 * character, the literal string `#` is appended to `result`. 161 * * The value of `urlObject.hash` is appended to `result`. 162 * * Otherwise, if the `urlObject.hash` property is not `undefined` and is not a 163 * string, an `Error` is thrown. 164 * * `result` is returned. 165 * @since v0.1.25 166 * @legacy Use the WHATWG URL API instead. 167 * @param urlObject A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. 168 */ 169 function format(urlObject: UrlObject | string): string; 170 /** 171 * The `url.resolve()` method resolves a target URL relative to a base URL in a 172 * manner similar to that of a Web browser resolving an anchor tag HREF. 173 * 174 * ```js 175 * import url from 'node:url'; 176 * url.resolve('/one/two/three', 'four'); // '/one/two/four' 177 * url.resolve('http://example.com/', '/one'); // 'http://example.com/one' 178 * url.resolve('http://example.com/one', '/two'); // 'http://example.com/two' 179 * ``` 180 * 181 * You can achieve the same result using the WHATWG URL API: 182 * 183 * ```js 184 * function resolve(from, to) { 185 * const resolvedUrl = new URL(to, new URL(from, 'resolve://')); 186 * if (resolvedUrl.protocol === 'resolve:') { 187 * // `from` is a relative URL. 188 * const { pathname, search, hash } = resolvedUrl; 189 * return pathname + search + hash; 190 * } 191 * return resolvedUrl.toString(); 192 * } 193 * 194 * resolve('/one/two/three', 'four'); // '/one/two/four' 195 * resolve('http://example.com/', '/one'); // 'http://example.com/one' 196 * resolve('http://example.com/one', '/two'); // 'http://example.com/two' 197 * ``` 198 * @since v0.1.25 199 * @legacy Use the WHATWG URL API instead. 200 * @param from The Base URL being resolved against. 201 * @param to The HREF URL being resolved. 202 */ 203 function resolve(from: string, to: string): string; 204 /** 205 * Returns the [Punycode](https://tools.ietf.org/html/rfc5891#section-4.4) ASCII serialization of the `domain`. If `domain` is an 206 * invalid domain, the empty string is returned. 207 * 208 * It performs the inverse operation to {@link domainToUnicode}. 209 * 210 * This feature is only available if the `node` executable was compiled with `ICU` enabled. If not, the domain names are passed through unchanged. 211 * 212 * ```js 213 * import url from 'node:url'; 214 * 215 * console.log(url.domainToASCII('español.com')); 216 * // Prints xn--espaol-zwa.com 217 * console.log(url.domainToASCII('中文.com')); 218 * // Prints xn--fiq228c.com 219 * console.log(url.domainToASCII('xn--iñvalid.com')); 220 * // Prints an empty string 221 * ``` 222 * @since v7.4.0, v6.13.0 223 */ 224 function domainToASCII(domain: string): string; 225 /** 226 * Returns the Unicode serialization of the `domain`. If `domain` is an invalid 227 * domain, the empty string is returned. 228 * 229 * It performs the inverse operation to {@link domainToASCII}. 230 * 231 * This feature is only available if the `node` executable was compiled with `ICU` enabled. If not, the domain names are passed through unchanged. 232 * 233 * ```js 234 * import url from 'node:url'; 235 * 236 * console.log(url.domainToUnicode('xn--espaol-zwa.com')); 237 * // Prints español.com 238 * console.log(url.domainToUnicode('xn--fiq228c.com')); 239 * // Prints 中文.com 240 * console.log(url.domainToUnicode('xn--iñvalid.com')); 241 * // Prints an empty string 242 * ``` 243 * @since v7.4.0, v6.13.0 244 */ 245 function domainToUnicode(domain: string): string; 246 /** 247 * This function ensures the correct decodings of percent-encoded characters as 248 * well as ensuring a cross-platform valid absolute path string. 249 * 250 * ```js 251 * import { fileURLToPath } from 'node:url'; 252 * 253 * const __filename = fileURLToPath(import.meta.url); 254 * 255 * new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/ 256 * fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows) 257 * 258 * new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt 259 * fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows) 260 * 261 * new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt 262 * fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX) 263 * 264 * new URL('file:///hello world').pathname; // Incorrect: /hello%20world 265 * fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) 266 * ``` 267 * @since v10.12.0 268 * @param url The file URL string or URL object to convert to a path. 269 * @return The fully-resolved platform-specific Node.js file path. 270 */ 271 function fileURLToPath(url: string | URL): string; 272 /** 273 * This function ensures that `path` is resolved absolutely, and that the URL 274 * control characters are correctly encoded when converting into a File URL. 275 * 276 * ```js 277 * import { pathToFileURL } from 'node:url'; 278 * 279 * new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 280 * pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) 281 * 282 * new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c 283 * pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX) 284 * ``` 285 * @since v10.12.0 286 * @param path The path to convert to a File URL. 287 * @return The file URL object. 288 */ 289 function pathToFileURL(path: string): URL; 290 /** 291 * This utility function converts a URL object into an ordinary options object as 292 * expected by the `http.request()` and `https.request()` APIs. 293 * 294 * ```js 295 * import { urlToHttpOptions } from 'node:url'; 296 * const myURL = new URL('https://a:b@測試?abc#foo'); 297 * 298 * console.log(urlToHttpOptions(myURL)); 299 * 300 * { 301 * protocol: 'https:', 302 * hostname: 'xn--g6w251d', 303 * hash: '#foo', 304 * search: '?abc', 305 * pathname: '/', 306 * path: '/?abc', 307 * href: 'https://a:b@xn--g6w251d/?abc#foo', 308 * auth: 'a:b' 309 * } 310 * 311 * ``` 312 * @since v15.7.0 313 * @param url The `WHATWG URL` object to convert to an options object. 314 * @return Options object 315 */ 316 function urlToHttpOptions(url: URL): ClientRequestArgs; 317 interface URLFormatOptions { 318 /** 319 * `true` if the serialized URL string should include the username and password, `false` otherwise. 320 * @default true 321 */ 322 auth?: boolean | undefined; 323 /** 324 * `true` if the serialized URL string should include the fragment, `false` otherwise. 325 * @default true 326 */ 327 fragment?: boolean | undefined; 328 /** 329 * `true` if the serialized URL string should include the search query, `false` otherwise. 330 * @default true 331 */ 332 search?: boolean | undefined; 333 /** 334 * `true` if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to 335 * being Punycode encoded. 336 * @default false 337 */ 338 unicode?: boolean | undefined; 339 } 340 /** 341 * Browser-compatible `URL` class, implemented by following the WHATWG URL 342 * Standard. [Examples of parsed URLs](https://url.spec.whatwg.org/#example-url-parsing) may be found in the Standard itself. 343 * The `URL` class is also available on the global object. 344 * 345 * In accordance with browser conventions, all properties of `URL` objects 346 * are implemented as getters and setters on the class prototype, rather than as 347 * data properties on the object itself. Thus, unlike `legacy urlObject` s, 348 * using the `delete` keyword on any properties of `URL` objects (e.g. `delete myURL.protocol`, `delete myURL.pathname`, etc) has no effect but will still 349 * return `true`. 350 * @since v7.0.0, v6.13.0 351 */ 352 class URL { 353 /** 354 * Creates a `'blob:nodedata:...'` URL string that represents the given `Blob` object and can be used to retrieve the `Blob` later. 355 * 356 * ```js 357 * import { 358 * Blob, 359 * resolveObjectURL, 360 * } from 'node:buffer'; 361 * 362 * const blob = new Blob(['hello']); 363 * const id = URL.createObjectURL(blob); 364 * 365 * // later... 366 * 367 * const otherBlob = resolveObjectURL(id); 368 * console.log(otherBlob.size); 369 * ``` 370 * 371 * The data stored by the registered `Blob` will be retained in memory until`URL.revokeObjectURL()` is called to remove it. 372 * 373 * `Blob` objects are registered within the current thread. If using Worker 374 * Threads, `Blob` objects registered within one Worker will not be available 375 * to other workers or the main thread. 376 * @since v16.7.0 377 * @experimental 378 */ 379 static createObjectURL(blob: Blob): string; 380 /** 381 * Removes the stored `Blob` identified by the given ID. 382 * @since v16.7.0 383 * @experimental 384 * @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`. 385 */ 386 static revokeObjectURL(id: string): void; 387 constructor(input: string | { toString: () => string }, base?: string | URL); 388 /** 389 * Gets and sets the fragment portion of the URL. 390 * 391 * ```js 392 * const myURL = new URL('https://example.org/foo#bar'); 393 * console.log(myURL.hash); 394 * // Prints #bar 395 * 396 * myURL.hash = 'baz'; 397 * console.log(myURL.href); 398 * // Prints https://example.org/foo#baz 399 * ``` 400 * 401 * Invalid URL characters included in the value assigned to the `hash` property 402 * are `percent-encoded`. The selection of which characters to 403 * percent-encode may vary somewhat from what the {@link parse} and {@link format} methods would produce. 404 */ 405 hash: string; 406 /** 407 * Gets and sets the host portion of the URL. 408 * 409 * ```js 410 * const myURL = new URL('https://example.org:81/foo'); 411 * console.log(myURL.host); 412 * // Prints example.org:81 413 * 414 * myURL.host = 'example.com:82'; 415 * console.log(myURL.href); 416 * // Prints https://example.com:82/foo 417 * ``` 418 * 419 * Invalid host values assigned to the `host` property are ignored. 420 */ 421 host: string; 422 /** 423 * Gets and sets the host name portion of the URL. The key difference between`url.host` and `url.hostname` is that `url.hostname` does _not_ include the 424 * port. 425 * 426 * ```js 427 * const myURL = new URL('https://example.org:81/foo'); 428 * console.log(myURL.hostname); 429 * // Prints example.org 430 * 431 * // Setting the hostname does not change the port 432 * myURL.hostname = 'example.com:82'; 433 * console.log(myURL.href); 434 * // Prints https://example.com:81/foo 435 * 436 * // Use myURL.host to change the hostname and port 437 * myURL.host = 'example.org:82'; 438 * console.log(myURL.href); 439 * // Prints https://example.org:82/foo 440 * ``` 441 * 442 * Invalid host name values assigned to the `hostname` property are ignored. 443 */ 444 hostname: string; 445 /** 446 * Gets and sets the serialized URL. 447 * 448 * ```js 449 * const myURL = new URL('https://example.org/foo'); 450 * console.log(myURL.href); 451 * // Prints https://example.org/foo 452 * 453 * myURL.href = 'https://example.com/bar'; 454 * console.log(myURL.href); 455 * // Prints https://example.com/bar 456 * ``` 457 * 458 * Getting the value of the `href` property is equivalent to calling {@link toString}. 459 * 460 * Setting the value of this property to a new value is equivalent to creating a 461 * new `URL` object using `new URL(value)`. Each of the `URL`object's properties will be modified. 462 * 463 * If the value assigned to the `href` property is not a valid URL, a `TypeError`will be thrown. 464 */ 465 href: string; 466 /** 467 * Gets the read-only serialization of the URL's origin. 468 * 469 * ```js 470 * const myURL = new URL('https://example.org/foo/bar?baz'); 471 * console.log(myURL.origin); 472 * // Prints https://example.org 473 * ``` 474 * 475 * ```js 476 * const idnURL = new URL('https://測試'); 477 * console.log(idnURL.origin); 478 * // Prints https://xn--g6w251d 479 * 480 * console.log(idnURL.hostname); 481 * // Prints xn--g6w251d 482 * ``` 483 */ 484 readonly origin: string; 485 /** 486 * Gets and sets the password portion of the URL. 487 * 488 * ```js 489 * const myURL = new URL('https://abc:xyz@example.com'); 490 * console.log(myURL.password); 491 * // Prints xyz 492 * 493 * myURL.password = '123'; 494 * console.log(myURL.href); 495 * // Prints https://abc:123@example.com 496 * ``` 497 * 498 * Invalid URL characters included in the value assigned to the `password` property 499 * are `percent-encoded`. The selection of which characters to 500 * percent-encode may vary somewhat from what the {@link parse} and {@link format} methods would produce. 501 */ 502 password: string; 503 /** 504 * Gets and sets the path portion of the URL. 505 * 506 * ```js 507 * const myURL = new URL('https://example.org/abc/xyz?123'); 508 * console.log(myURL.pathname); 509 * // Prints /abc/xyz 510 * 511 * myURL.pathname = '/abcdef'; 512 * console.log(myURL.href); 513 * // Prints https://example.org/abcdef?123 514 * ``` 515 * 516 * Invalid URL characters included in the value assigned to the `pathname` property are `percent-encoded`. The selection of which characters 517 * to percent-encode may vary somewhat from what the {@link parse} and {@link format} methods would produce. 518 */ 519 pathname: string; 520 /** 521 * Gets and sets the port portion of the URL. 522 * 523 * The port value may be a number or a string containing a number in the range `0` to `65535` (inclusive). Setting the value to the default port of the `URL` objects given `protocol` will 524 * result in the `port` value becoming 525 * the empty string (`''`). 526 * 527 * The port value can be an empty string in which case the port depends on 528 * the protocol/scheme: 529 * 530 * <omitted> 531 * 532 * Upon assigning a value to the port, the value will first be converted to a 533 * string using `.toString()`. 534 * 535 * If that string is invalid but it begins with a number, the leading number is 536 * assigned to `port`. 537 * If the number lies outside the range denoted above, it is ignored. 538 * 539 * ```js 540 * const myURL = new URL('https://example.org:8888'); 541 * console.log(myURL.port); 542 * // Prints 8888 543 * 544 * // Default ports are automatically transformed to the empty string 545 * // (HTTPS protocol's default port is 443) 546 * myURL.port = '443'; 547 * console.log(myURL.port); 548 * // Prints the empty string 549 * console.log(myURL.href); 550 * // Prints https://example.org/ 551 * 552 * myURL.port = 1234; 553 * console.log(myURL.port); 554 * // Prints 1234 555 * console.log(myURL.href); 556 * // Prints https://example.org:1234/ 557 * 558 * // Completely invalid port strings are ignored 559 * myURL.port = 'abcd'; 560 * console.log(myURL.port); 561 * // Prints 1234 562 * 563 * // Leading numbers are treated as a port number 564 * myURL.port = '5678abcd'; 565 * console.log(myURL.port); 566 * // Prints 5678 567 * 568 * // Non-integers are truncated 569 * myURL.port = 1234.5678; 570 * console.log(myURL.port); 571 * // Prints 1234 572 * 573 * // Out-of-range numbers which are not represented in scientific notation 574 * // will be ignored. 575 * myURL.port = 1e10; // 10000000000, will be range-checked as described below 576 * console.log(myURL.port); 577 * // Prints 1234 578 * ``` 579 * 580 * Numbers which contain a decimal point, 581 * such as floating-point numbers or numbers in scientific notation, 582 * are not an exception to this rule. 583 * Leading numbers up to the decimal point will be set as the URL's port, 584 * assuming they are valid: 585 * 586 * ```js 587 * myURL.port = 4.567e21; 588 * console.log(myURL.port); 589 * // Prints 4 (because it is the leading number in the string '4.567e21') 590 * ``` 591 */ 592 port: string; 593 /** 594 * Gets and sets the protocol portion of the URL. 595 * 596 * ```js 597 * const myURL = new URL('https://example.org'); 598 * console.log(myURL.protocol); 599 * // Prints https: 600 * 601 * myURL.protocol = 'ftp'; 602 * console.log(myURL.href); 603 * // Prints ftp://example.org/ 604 * ``` 605 * 606 * Invalid URL protocol values assigned to the `protocol` property are ignored. 607 */ 608 protocol: string; 609 /** 610 * Gets and sets the serialized query portion of the URL. 611 * 612 * ```js 613 * const myURL = new URL('https://example.org/abc?123'); 614 * console.log(myURL.search); 615 * // Prints ?123 616 * 617 * myURL.search = 'abc=xyz'; 618 * console.log(myURL.href); 619 * // Prints https://example.org/abc?abc=xyz 620 * ``` 621 * 622 * Any invalid URL characters appearing in the value assigned the `search`property will be `percent-encoded`. The selection of which 623 * characters to percent-encode may vary somewhat from what the {@link parse} and {@link format} methods would produce. 624 */ 625 search: string; 626 /** 627 * Gets the `URLSearchParams` object representing the query parameters of the 628 * URL. This property is read-only but the `URLSearchParams` object it provides 629 * can be used to mutate the URL instance; to replace the entirety of query 630 * parameters of the URL, use the {@link search} setter. See `URLSearchParams` documentation for details. 631 * 632 * Use care when using `.searchParams` to modify the `URL` because, 633 * per the WHATWG specification, the `URLSearchParams` object uses 634 * different rules to determine which characters to percent-encode. For 635 * instance, the `URL` object will not percent encode the ASCII tilde (`~`) 636 * character, while `URLSearchParams` will always encode it: 637 * 638 * ```js 639 * const myUrl = new URL('https://example.org/abc?foo=~bar'); 640 * 641 * console.log(myUrl.search); // prints ?foo=~bar 642 * 643 * // Modify the URL via searchParams... 644 * myUrl.searchParams.sort(); 645 * 646 * console.log(myUrl.search); // prints ?foo=%7Ebar 647 * ``` 648 */ 649 readonly searchParams: URLSearchParams; 650 /** 651 * Gets and sets the username portion of the URL. 652 * 653 * ```js 654 * const myURL = new URL('https://abc:xyz@example.com'); 655 * console.log(myURL.username); 656 * // Prints abc 657 * 658 * myURL.username = '123'; 659 * console.log(myURL.href); 660 * // Prints https://123:xyz@example.com/ 661 * ``` 662 * 663 * Any invalid URL characters appearing in the value assigned the `username` property will be `percent-encoded`. The selection of which 664 * characters to percent-encode may vary somewhat from what the {@link parse} and {@link format} methods would produce. 665 */ 666 username: string; 667 /** 668 * The `toString()` method on the `URL` object returns the serialized URL. The 669 * value returned is equivalent to that of {@link href} and {@link toJSON}. 670 */ 671 toString(): string; 672 /** 673 * The `toJSON()` method on the `URL` object returns the serialized URL. The 674 * value returned is equivalent to that of {@link href} and {@link toString}. 675 * 676 * This method is automatically called when an `URL` object is serialized 677 * with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). 678 * 679 * ```js 680 * const myURLs = [ 681 * new URL('https://www.example.com'), 682 * new URL('https://test.example.org'), 683 * ]; 684 * console.log(JSON.stringify(myURLs)); 685 * // Prints ["https://www.example.com/","https://test.example.org/"] 686 * ``` 687 */ 688 toJSON(): string; 689 } 690 interface URLSearchParamsIterator<T> extends NodeJS.Iterator<T, NodeJS.BuiltinIteratorReturn, unknown> { 691 [Symbol.iterator](): URLSearchParamsIterator<T>; 692 } 693 /** 694 * The `URLSearchParams` API provides read and write access to the query of a `URL`. The `URLSearchParams` class can also be used standalone with one of the 695 * four following constructors. 696 * The `URLSearchParams` class is also available on the global object. 697 * 698 * The WHATWG `URLSearchParams` interface and the `querystring` module have 699 * similar purpose, but the purpose of the `querystring` module is more 700 * general, as it allows the customization of delimiter characters (`&` and `=`). 701 * On the other hand, this API is designed purely for URL query strings. 702 * 703 * ```js 704 * const myURL = new URL('https://example.org/?abc=123'); 705 * console.log(myURL.searchParams.get('abc')); 706 * // Prints 123 707 * 708 * myURL.searchParams.append('abc', 'xyz'); 709 * console.log(myURL.href); 710 * // Prints https://example.org/?abc=123&abc=xyz 711 * 712 * myURL.searchParams.delete('abc'); 713 * myURL.searchParams.set('a', 'b'); 714 * console.log(myURL.href); 715 * // Prints https://example.org/?a=b 716 * 717 * const newSearchParams = new URLSearchParams(myURL.searchParams); 718 * // The above is equivalent to 719 * // const newSearchParams = new URLSearchParams(myURL.search); 720 * 721 * newSearchParams.append('a', 'c'); 722 * console.log(myURL.href); 723 * // Prints https://example.org/?a=b 724 * console.log(newSearchParams.toString()); 725 * // Prints a=b&a=c 726 * 727 * // newSearchParams.toString() is implicitly called 728 * myURL.search = newSearchParams; 729 * console.log(myURL.href); 730 * // Prints https://example.org/?a=b&a=c 731 * newSearchParams.delete('a'); 732 * console.log(myURL.href); 733 * // Prints https://example.org/?a=b&a=c 734 * ``` 735 * @since v7.5.0, v6.13.0 736 */ 737 class URLSearchParams implements Iterable<[string, string]> { 738 constructor( 739 init?: 740 | URLSearchParams 741 | string 742 | Record<string, string | readonly string[]> 743 | Iterable<[string, string]> 744 | ReadonlyArray<[string, string]>, 745 ); 746 readonly size: number; 747 /** 748 * Append a new name-value pair to the query string. 749 */ 750 append(name: string, value: string): void; 751 /** 752 * Remove all name-value pairs whose name is `name`. 753 */ 754 delete(name: string): void; 755 /** 756 * Returns an ES6 `Iterator` over each of the name-value pairs in the query. 757 * Each item of the iterator is a JavaScript `Array`. The first item of the `Array`is the `name`, the second item of the `Array` is the `value`. 758 * 759 * Alias for `urlSearchParams[@@iterator]()`. 760 */ 761 entries(): URLSearchParamsIterator<[string, string]>; 762 /** 763 * Iterates over each name-value pair in the query and invokes the given function. 764 * 765 * ```js 766 * const myURL = new URL('https://example.org/?a=b&c=d'); 767 * myURL.searchParams.forEach((value, name, searchParams) => { 768 * console.log(name, value, myURL.searchParams === searchParams); 769 * }); 770 * // Prints: 771 * // a b true 772 * // c d true 773 * ``` 774 * @param fn Invoked for each name-value pair in the query 775 * @param thisArg To be used as `this` value for when `fn` is called 776 */ 777 forEach<TThis = this>( 778 fn: (this: TThis, value: string, name: string, searchParams: URLSearchParams) => void, 779 thisArg?: TThis, 780 ): void; 781 /** 782 * Returns the value of the first name-value pair whose name is `name`. If there 783 * are no such pairs, `null` is returned. 784 * @return or `null` if there is no name-value pair with the given `name`. 785 */ 786 get(name: string): string | null; 787 /** 788 * Returns the values of all name-value pairs whose name is `name`. If there are 789 * no such pairs, an empty array is returned. 790 */ 791 getAll(name: string): string[]; 792 /** 793 * Returns `true` if there is at least one name-value pair whose name is `name`. 794 */ 795 has(name: string): boolean; 796 /** 797 * Returns an ES6 `Iterator` over the names of each name-value pair. 798 * 799 * ```js 800 * const params = new URLSearchParams('foo=bar&foo=baz'); 801 * for (const name of params.keys()) { 802 * console.log(name); 803 * } 804 * // Prints: 805 * // foo 806 * // foo 807 * ``` 808 */ 809 keys(): URLSearchParamsIterator<string>; 810 /** 811 * Sets the value in the `URLSearchParams` object associated with `name` to`value`. If there are any pre-existing name-value pairs whose names are `name`, 812 * set the first such pair's value to `value` and remove all others. If not, 813 * append the name-value pair to the query string. 814 * 815 * ```js 816 * const params = new URLSearchParams(); 817 * params.append('foo', 'bar'); 818 * params.append('foo', 'baz'); 819 * params.append('abc', 'def'); 820 * console.log(params.toString()); 821 * // Prints foo=bar&foo=baz&abc=def 822 * 823 * params.set('foo', 'def'); 824 * params.set('xyz', 'opq'); 825 * console.log(params.toString()); 826 * // Prints foo=def&abc=def&xyz=opq 827 * ``` 828 */ 829 set(name: string, value: string): void; 830 /** 831 * Sort all existing name-value pairs in-place by their names. Sorting is done 832 * with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs 833 * with the same name is preserved. 834 * 835 * This method can be used, in particular, to increase cache hits. 836 * 837 * ```js 838 * const params = new URLSearchParams('query[]=abc&type=search&query[]=123'); 839 * params.sort(); 840 * console.log(params.toString()); 841 * // Prints query%5B%5D=abc&query%5B%5D=123&type=search 842 * ``` 843 * @since v7.7.0, v6.13.0 844 */ 845 sort(): void; 846 /** 847 * Returns the search parameters serialized as a string, with characters 848 * percent-encoded where necessary. 849 */ 850 toString(): string; 851 /** 852 * Returns an ES6 `Iterator` over the values of each name-value pair. 853 */ 854 values(): URLSearchParamsIterator<string>; 855 [Symbol.iterator](): URLSearchParamsIterator<[string, string]>; 856 } 857 858 import { URL as _URL, URLSearchParams as _URLSearchParams } from "url"; 859 global { 860 interface URLSearchParams extends _URLSearchParams {} 861 interface URL extends _URL {} 862 interface Global { 863 URL: typeof _URL; 864 URLSearchParams: typeof _URLSearchParams; 865 } 866 /** 867 * `URL` class is a global reference for `import { URL } from 'node:url'` 868 * https://nodejs.org/api/url.html#the-whatwg-url-api 869 * @since v10.0.0 870 */ 871 var URL: 872 // For compatibility with "dom" and "webworker" URL declarations 873 typeof globalThis extends { onmessage: any; URL: infer URL } ? URL 874 : typeof _URL; 875 /** 876 * `URLSearchParams` class is a global reference for `import { URLSearchParams } from 'node:url'`. 877 * https://nodejs.org/api/url.html#class-urlsearchparams 878 * @since v10.0.0 879 */ 880 var URLSearchParams: 881 // For compatibility with "dom" and "webworker" URLSearchParams declarations 882 typeof globalThis extends { onmessage: any; URLSearchParams: infer URLSearchParams } ? URLSearchParams 883 : typeof _URLSearchParams; 884 } 885 } 886 declare module "node:url" { 887 export * from "url"; 888 }