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