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