@types/node 20.19.25 → 24.10.3

{node v20.19 → node v24.10}/url.d.ts

@@ -5,7 +5,7 @@
  * ```js
  * import url from 'node:url';
  * ```
- * @see [source](https://github.com/nodejs/node/blob/v20.13.1/lib/url.js)
+ * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/url.js)
  */
 declare module "url" {
     import { Blob as NodeBlob, NonSharedBuffer } from "node:buffer";
@@ -50,10 +50,18 @@ declare module "url" {
         /**
          * `true` if the `path` should be return as a windows filepath, `false` for posix, and `undefined` for the system default.
          * @default undefined
+         * @since v22.1.0
+         */
+        windows?: boolean | undefined;
+    }
+    interface PathToFileUrlOptions {
+        /**
+         * `true` if the `path` should be return as a windows filepath, `false` for posix, and `undefined` for the system default.
+         * @default undefined
+         * @since v22.1.0
          */
         windows?: boolean | undefined;
     }
-    interface PathToFileUrlOptions extends FileUrlToPathOptions {}
     /**
      * The `url.parse()` method takes a URL string, parses it, and returns a URL
      * object.
@@ -63,20 +71,44 @@ declare module "url" {
      * A `URIError` is thrown if the `auth` property is present but cannot be decoded.
      *
      * `url.parse()` uses a lenient, non-standard algorithm for parsing URL
-     * 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
-     * input. CVEs are not issued for `url.parse()` vulnerabilities. Use the `WHATWG URL` API instead.
+     * 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
+     * input. CVEs are not issued for `url.parse()` vulnerabilities. Use the
+     * [WHATWG URL](https://nodejs.org/docs/latest-v24.x/api/url.html#the-whatwg-url-api) API instead, for example:
+     *
+     * ```js
+     * function getURL(req) {
+     *   const proto = req.headers['x-forwarded-proto'] || 'https';
+     *   const host = req.headers['x-forwarded-host'] || req.headers.host || 'example.com';
+     *   return new URL(req.url || '/', `${proto}://${host}`);
+     * }
+     * ```
+     *
+     * The example above assumes well-formed headers are forwarded from a reverse
+     * proxy to your Node.js server. If you are not using a reverse proxy, you should
+     * use the example below:
+     *
+     * ```js
+     * function getURL(req) {
+     *   return new URL(req.url || '/', 'https://example.com');
+     * }
+     * ```
      * @since v0.1.25
      * @deprecated Use the WHATWG URL API instead.
      * @param urlString The URL string to parse.
-     * @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
-     * on the returned URL object will be an unparsed, undecoded string.
-     * @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
-     * result would be `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`.
+     * @param parseQueryString If `true`, the `query` property will always
+     * be set to an object returned by the [`querystring`](https://nodejs.org/docs/latest-v24.x/api/querystring.html) module's `parse()`
+     * method. If `false`, the `query` property on the returned URL object will be an
+     * unparsed, undecoded string. **Default:** `false`.
+     * @param slashesDenoteHost 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 result would be
+     * `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`.
+     * **Default:** `false`.
      */
-    function parse(urlString: string): UrlWithStringQuery;
     function parse(
         urlString: string,
-        parseQueryString: false | undefined,
+        parseQueryString?: false,
         slashesDenoteHost?: boolean,
     ): UrlWithStringQuery;
     function parse(urlString: string, parseQueryString: true, slashesDenoteHost?: boolean): UrlWithParsedQuery;
@@ -307,6 +339,17 @@ declare module "url" {
      * @return The fully-resolved platform-specific Node.js file path.
      */
     function fileURLToPath(url: string | URL, options?: FileUrlToPathOptions): string;
+    /**
+     * Like `url.fileURLToPath(...)` except that instead of returning a string
+     * representation of the path, a `Buffer` is returned. This conversion is
+     * helpful when the input URL contains percent-encoded segments that are
+     * not valid UTF-8 / Unicode sequences.
+     * @since v24.3.0
+     * @param url The file URL string or URL object to convert to a path.
+     * @returns The fully-resolved platform-specific Node.js file path
+     * as a `Buffer`.
+     */
+    function fileURLToPathBuffer(url: string | URL, options?: FileUrlToPathOptions): NonSharedBuffer;
     /**
      * This function ensures that `path` is resolved absolutely, and that the URL
      * control characters are correctly encoded when converting into a File URL.
@@ -412,14 +455,12 @@ declare module "url" {
          * Threads, `Blob` objects registered within one Worker will not be available
          * to other workers or the main thread.
          * @since v16.7.0
-         * @experimental
          */
         static createObjectURL(blob: NodeBlob): string;
         /**
          * Removes the stored `Blob` identified by the given ID. Attempting to revoke a
          * ID that isn't registered will silently fail.
          * @since v16.7.0
-         * @experimental
          * @param id A `'blob:nodedata:...` URL string returned by a prior call to `URL.createObjectURL()`.
          */
         static revokeObjectURL(id: string): void;
@@ -438,12 +479,15 @@ declare module "url" {
          */
         static canParse(input: string, base?: string): boolean;
         /**
-         * Parses a string as a URL. If `base` is provided, it will be used as the base URL for the purpose of resolving non-absolute `input` URLs.
-         * Returns `null` if `input` is not a valid.
-         * @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
-         * `converted to a string` first.
-         * @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.
-         * @since v20.18.0
+         * Parses a string as a URL. If `base` is provided, it will be used as the base
+         * URL for the purpose of resolving non-absolute `input` URLs. Returns `null`
+         * if the parameters can't be resolved to a valid URL.
+         * @since v22.1.0
+         * @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 [converted to a string](https://tc39.es/ecma262/#sec-tostring) first.
+         * @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](https://tc39.es/ecma262/#sec-tostring) first.
          */
         static parse(input: string, base?: string): URL | null;
         constructor(input: string | { toString: () => string }, base?: string | URL);
@@ -749,6 +793,54 @@ declare module "url" {
          */
         toJSON(): string;
     }
+    interface URLPatternComponentResult {
+        input: string;
+        groups: Record<string, string | undefined>;
+    }
+    interface URLPatternInit {
+        protocol?: string;
+        username?: string;
+        password?: string;
+        hostname?: string;
+        port?: string;
+        pathname?: string;
+        search?: string;
+        hash?: string;
+        baseURL?: string;
+    }
+    interface URLPatternOptions {
+        ignoreCase?: boolean;
+    }
+    interface URLPatternResult {
+        inputs: (string | URLPatternInit)[];
+        protocol: URLPatternComponentResult;
+        username: URLPatternComponentResult;
+        password: URLPatternComponentResult;
+        hostname: URLPatternComponentResult;
+        port: URLPatternComponentResult;
+        pathname: URLPatternComponentResult;
+        search: URLPatternComponentResult;
+        hash: URLPatternComponentResult;
+    }
+    /**
+     * @since v23.8.0
+     * @experimental
+     */
+    class URLPattern {
+        constructor(input: string | URLPatternInit, baseURL: string, options?: URLPatternOptions);
+        constructor(input?: string | URLPatternInit, options?: URLPatternOptions);
+        exec(input?: string | URLPatternInit, baseURL?: string): URLPatternResult | null;
+        readonly hasRegExpGroups: boolean;
+        readonly hash: string;
+        readonly hostname: string;
+        readonly password: string;
+        readonly pathname: string;
+        readonly port: string;
+        readonly protocol: string;
+        readonly search: string;
+        test(input?: string | URLPatternInit, baseURL?: string): boolean;
+        readonly username: string;
+    }
     interface URLSearchParamsIterator<T> extends NodeJS.Iterator<T, NodeJS.BuiltinIteratorReturn, unknown> {
         [Symbol.iterator](): URLSearchParamsIterator<T>;
     }
@@ -820,7 +912,7 @@ declare module "url" {
          * Returns an ES6 `Iterator` over each of the name-value pairs in the query.
          * 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`.
          *
-         * Alias for `urlSearchParams[@@iterator]()`.
+         * Alias for `urlSearchParams[Symbol.iterator]()`.
          */
         entries(): URLSearchParamsIterator<[string, string]>;
         /**
@@ -929,34 +1021,35 @@ declare module "url" {
         values(): URLSearchParamsIterator<string>;
         [Symbol.iterator](): URLSearchParamsIterator<[string, string]>;
     }
-    import { URL as _URL, URLSearchParams as _URLSearchParams } from "url";
+    import {
+        URL as _URL,
+        URLPattern as _URLPattern,
+        URLPatternInit as _URLPatternInit,
+        URLPatternResult as _URLPatternResult,
+        URLSearchParams as _URLSearchParams,
+    } from "url";
     global {
-        interface URLSearchParams extends _URLSearchParams {}
         interface URL extends _URL {}
-        interface Global {
-            URL: typeof _URL;
-            URLSearchParams: typeof _URLSearchParams;
-        }
-        /**
-         * `URL` class is a global reference for `import { URL } from 'node:url'`
-         * https://nodejs.org/api/url.html#the-whatwg-url-api
-         * @since v10.0.0
-         */
         var URL: typeof globalThis extends {
             onmessage: any;
             URL: infer T;
         } ? T
             : typeof _URL;
-        /**
-         * `URLSearchParams` class is a global reference for `import { URLSearchParams } from 'node:url'`
-         * https://nodejs.org/api/url.html#class-urlsearchparams
-         * @since v10.0.0
-         */
+        interface URLSearchParams extends _URLSearchParams {}
         var URLSearchParams: typeof globalThis extends {
             onmessage: any;
             URLSearchParams: infer T;
         } ? T
             : typeof _URLSearchParams;
+        interface URLPatternInit extends _URLPatternInit {}
+        interface URLPatternResult extends _URLPatternResult {}
+        interface URLPattern extends _URLPattern {}
+        var URLPattern: typeof globalThis extends {
+            onmessage: any;
+            scheduler: any; // Must be a var introduced at the same time as URLPattern.
+            URLPattern: infer T;
+        } ? T
+            : typeof _URLPattern;
     }
 }
 declare module "node:url" {