f0f1f831e67d9097281eaf595160749636bff994ab2baaac0361e408582e36904f68310da45960a3e26eb3b6536bebc8104edda87446d60cf7a1336748dc11 44 KB

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